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This tutorial gives an introduction to writing GTK+ 3 applications in Python. 


Prior to working through this tutorial, 1t is recommended that you have a reasonable grasp of the Python 
programming language. GUI programming introduces new problems compared to interacting with the 
standard output (console / terminal). It is necessary for you to know how to create and run Python files, 
understand basic interpreter errors, and work with strings, integers, floats and Boolean values. For the 
more advanced widgets in this tutorial, good knowledge of lists and tuples will be needed. 


Although this tutorial describes the most important classes and methods within GT'K+ 3, it is not supposed 
to serve as an API reference. Please refer to the[GTK+ 3 Reference Manual|for a detailed description of 
the API. Also thereás a|Python-specific referenceJavailable. 
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1. Installatior AY] 


The first step before we start with actual coding consists of setting up|PyGObject|and its dependencies. 
PyGObject is a Python module that enables developers to access GObject-based libraries such as GTK+ 
within Python. It exclusively supports GT'K+ version 3 or later. 


1.1. DependenciesAJ] 


e GTK+3 
e Python 2 (2.6 or later) or Python 3 (3.1 or later) 


e gobject-introspection 


1.2. Prebuilt PackagesAY] 


Recent versions of PyGObject and its dependencies are packaged by nearly all major Linux distributions. 
So, If you use Linux, you can probably get started by installing the package from the official repository for 
your distribution. 


1.3. Installing From SourceAY| 


The easiest way to install PyGObject from source is using |JHBuild| It is designed to easily build source 
packages and discover what dependencies need to be build and in what order. To setup JHBuild, please 


follow the |JHBuild manual 


Once you have installed JHBuild successfully, download the latest configuration from] 1] Copy files with 
the suffix modules to JHBuildás module directory and the file sample-tarball.¡hbuildrc to /.¡hbuildrc. 


If you have not done it before, verify that your build environment is setup correctly by running: 
$ jhbuild sanitycheck 


It will print any applications and libraries that are currently missing on your system but required for 


building. You should install those using your distributionás package repository. A list of 
for different distributions is maintained on the GNOME wiki. Run the command above again to ensure the 


required tools are present. 


Executing the following command will build PyGObject and all its dependencies: 


$ jhbuild build pygobject 


Finally, you might want to install GTK+ from source as well: 


$ jhbuild build gtk+-3 
To start a shell with the same environment as used by JHBuild, run: 


$ jhbuild shell 


Next|Previous 


O Copyright GNU Free Documentation License 1.3 Revision £d9dd7a4. 


Built with using a[theme]provided by [Read the Docs 


Read the Docs v: latest 


Versions 
atest 


= 


Downloads 


Free document hosting provided by|Read the Docs 


Python GTK+ 3 Tutorial 


latest 


| 


. Installation 
. Getting Started 


O |2.1. Simple Example 
O |2.2. Extended Example 


. How to Deal With Strings 
. Widget Galler 

. Layout Containers 

. Labe 

. Entr 

. Button Widgets 

0. Expander, 


0 
A 


=|[Ne RTS eje pe 
ua) 

pa] 

Un 

2. 

e, el 

2] 


sn 
a 
el 


U 


2. Spinner 

3. Tree and List Widgets 
4. CellRenderers 

5. ComboBox 

6. IconView 

7. Multiline Text Editor 
8. Dialogs 

9. Popovers 

0. Clipboard 

1. Drag and Drop 

2. Glade and Gtk.Builder 
3. Objects 

4. Application 


O 
D 
YD 
Y 
ES 
E 


N 


NO) 


OU 
e] 
yo] 
el 
o 
O 
[ab] 
ep 
0 
Aa 


ee 
SD 
[oy 
En 
o 


o... 
< 
O 
= 
= 
Un 


Python GTK+ 3 Tutorial 


Doc» 


. Getting Started 
dit on GitHub 


($0) 


es 


2. Getting StartedAJ] 
2.1. Simple ExampldAY] 


To start with our tutorial we create the simplest program possible. This program will create an empty 200 
x 200 pixel window. 


simple _example.py X 


import gi 


gi.require_version("Gtk", "3.0") 
from gi.repository import Gtk 


win = Gtk.Window () 

win.connect ("destroy", Gtk.main_quit) 
win.show_all () 

Gtk.main () 


00 J0 04 0UnNnN RA 


We will now explain each line of the example. 
import gi 


gi.require_version("Gtk", "3.0") 
from gi.repository import Gtk 


In the beginning, we have to import the Gtk module to be able to access GTK+ás classes and functions. 
Since a userás system can have multiple versions of GTK+ installed at the same, we want to make sure 
that when we import Gtk that 1t refers to GTK+ 3 and not any other version of the library, which is the 
purpose of the statement gi.require_version('Gtk"”, '3.0'). 


The next line creates an empty window. 


win = Gtk.Window () 


Followed by connecting to the windowás delete event to ensure that the application is terminated if we 
click on the x to close the window. 


win.connect ("destroy", Gtk.main_quit) 


In the next step we display the window. 


win.show_all () 


Finally, we start the GTK+ processing loop which we quit when the window is closed (see line 6). 


Gtk.main () 


To run the program, open a terminal, change to the directory of the file, and enter: 


python simple_example.py 


2.2. Extended ExampleAY] 


For something a little more useful, hereás the PyGObject version of the classic ¿Hello Worldá program. 


Hello... X 


Click Here 


import gi 


gi.require_version("Gtk", "3.0") 
from gi.repository import Gtk 


class MyWindow(Gtk.Window) : 
def __init__ (self): 
super ().__init__(title="Hello World") 


self.button = Gtk.Button(label="Click Here") 
self .button.connect ("clicked", self.on_button_clicked) 
self.add(self.button) 


def on_button_clicked(self, widget): 
print ("Hello World") 


0 J3J0 Us WN ROwOoO Jocs yn Aa 


19 win = MyWindow () 

20 win.connect ("destroy", Gtk.main_quit) 
21 win.show_all () 

22 Gtk.main () 


This example differs from the simple example as we sub-class|Gt k . Window|to define our own 
MyWindow class. 


class MyWindow (Gtk.Window) : 


In the classás constructor we have to call the constructor of the super class. In addition, we tell it to set the 
value of the property title to Hello World. 


super ().__init__(title="Hello World") 


The next three lines are used to create a button widget, connect to its clicked signal and add it as child to 
the top-level window. 


self.button = Gtk.Button(label="Click Here") 


self.button.connect ("clicked", self.on_button_clicked) 
self.add (self.button) 


Accordingly, the method on_button_clicked () will be called 1f you click on the button. 


def on_button_clicked (self, widget): 
print ("Hello World") 


The last block, outside of the class, is very similar to the simple example above, but instead of creating an 


instance of the generic[Gtk . Windowj|class, we create an instance of MyWindow. 
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3. BasicsAJ] 


This section will introduce some of the most important aspects of GTK+. 


3.1. Main loop and SignalsA Y] 


Like most GUI toolkits, GTK+ uses an event-driven programming model. When the user is doing nothing, 
GTK+ sits in the main loop and waits for input. If the user performs some action - say, a mouse click - 
then the main loop 4wakes upá and delivers an event to GTK+. 


When widgets receive an event, they frequently emit one or more signals. Signals notify your program that 
ásomething interesting happenedá by invoking functions youáve connected to the signal. Such functions 
are commonly known as callbacks. When your callbacks are invoked, you would typically take some 
action - for example, when an Open button is clicked you might display a file chooser dialog. After a 
callback finishes, GTK+ will return to the main loop and await more user input. 


A generic example is: 


handler_id = widget.connect ("event", callback, data) 


Firstly, widget is an instance of a widget we created earlier. Next, the event we are interested in. Each 
widget has its own particular events which can occur. For instance, if you have a button you usually want 
to connect to the áclickedá event. This means that when the button is clicked, the signal is issued. Thirdly, 
the callback argument is the name of the callback function. It contains the code which runs when signals 
of the specified type are issued. Finally, the data argument includes any data which should be passed when 
the signal is issued. However, this argument is completely optional and can be left out if not required. 


The function returns a number that identifies this particular signal-callback pair. It is required to 
disconnect from a signal such that the callback function will not be called during any future or currently 
ongoing emissions of the signal it has been connected to. 


widget .disconnect (handler_id) 


If you have lost the áhandler_idá for some reason (for example the handlers were installed using 
Gtk.Builder.connect_signals ()), you can still disconnect a specific callback using the function 
disconnect_by_func(): 


widget .disconnect_by_func (callback) 


Applications should connect to the ádestroyá signal of the top-level window. It is emitted when an object 
1s destroyed, so when a user requests that a toplevel window is closed, the default handler for this signal 
destroys the window, but does not terminate the application. Connecting the ádestroyá signal of the 


top-level window to the function[Gtk.main_quit () [will result in the desired behaviour. 


window.connect ("destroy", Gtk.main_quit) 


Calling[Gtk .main_quit O) ]makes the main loop inside of! [Stk main () Jreturn. 
3.2. PropertiesAJ] 


Properties describe the configuration and state of widgets. As for signals, each widget has 1ts own 
particular set of properties. For example, a button has the property álabelá which contains the text of the 
label widget inside the button. You can specify the name and value of any number of properties as 
keyword arguments when creating an instance of a widget. To create a label aligned to the right with the 
text áHello Worldá and an angle of 25 degrees, use: 


label = Gtk.Label (label="Hello World", angle=25, halign=Gtk.Align.END) 


which is equivalent to 


label = Gtk.Label () 
label.set_label ("Hello World") 
label.set_angle (25) 
label.set_halign(Gtk.Align.END) 


Instead of using getters and setters you can also get and set the gobject properties through the ápropsá 
property such as widget .props.prop_name = value. This is equivalent to the more verbose 
widget .get_property ("prop-name") and widget .set_property ("prop-name", 
value). 


To see which properties are available for a widget in the running version of GTK you can ádirá the 
ápropsá property: 


widget = Gtk.Box() 
print (dir (widget .props)) 


This will print in the console the list of properties a Gtk.Box has. 
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4. How to Deal With StringsAJ] 


This section explains how strings are represented in Python 2.x, Python 3.x and GT'K+ and discusses 
common errors that arise when working with strings. 


4.1. DefinitiongAJ] 


A CADA AMA 


representations and their meaning depends on the language and context they are used in. The Unicode 
standard describes how characters are represented by code points. For example the characters above are 
represented with the code points U+0041, U+0042, U+0043, and U+00C9, respectively. Basically, code 
points are numbers in the range from 0 to 0x10FFFF. 


As mentioned earlier, the representation of a string as a list of code points is abstract. In order to convert 
this abstract representation into a sequence of bytes, the Unicode string must be encoded. The simplest 
form of encoding is ASCH and is performed as follows: 


1. If the code point is < 128, each byte is the same as the value of the code point. 


2. If the code point is 128 or greater, the Unicode string canát be represented in this encoding. (Python 
raises a UnicodeEncodeError exception in this case.) 


Although ASCH encoding is simple to apply it can only encode for 128 different characters which is 
hardly enough. One of the most commonly used encodings that addresses this problem is UTF-8 (it can 
handle any Unicode code point). UTE stands for ¿Unicode Transformation Formatá, and the 484 means 
that 8-bit numbers are used in the encoding. 


4.2. Python 
4.2.1. Python 2.xás Unicode SupporfAJ] 


Python 2 comes with two different kinds of objects that can be used to represent strings, str and 
unicode. Instances of the latter are used to express Unicode strings, whereas instances of the st r type 
are byte representations (the encoded string). Under the hood, Python represents Unicode strings as either 
16- or 32-bit integers, depending on how the Python interpreter was compiled. Unicode strings can be 
converted to 8-bit strings with unicode .encode (): 


>>> unicode_string = u"Fulu00dfb1u00e41le" 
>>> print unicode_string 

FuAbAalle 

>>> type(unicode_string) 

<type 'unicode'> 

>>> unicode_string.encode ("utf-8") 
"FuiXxc3Nx9fb1xc31xa41lle” 


Pythonás 8-bit strings have a str .decode () method that interprets the string using the given encoding: 


>>> utf8_string = unicode_string.encode ("utíf-8") 
>>> type(utf8_string) 

<type 'str'> 

>>> u2 = utf8_string.decode ("utf-8") 

>>> unicode_string == u2 

True 


Unfortunately, Python 2.x allows you to mix unicode and st r if the 8-bit string happened to contain 
only 7-bit (ASCID bytes, but would get UnicodeDecodeError if it contained non-ASCU values: 


>>> utf8_string = " sind rund" 
>>> unicode_string + utf8_string 
u'Fulxdfb1xe4lle sind rund” 
>>> utf8_string = " kixc3ixbónnten rund sein" 
>>> print utf8_string 

kAfnnten rund sein 
>>> unicode_string + utf8_string 
Traceback (most recent call last): 

File "<stdin>", line 1, in <module> 
UnicodeDecodeError: 'ascii' codec can't decode byte 0xc3 in position 2: 
ordinal not in range(128) 


4.2.2. Unicode in GTK+ÁJ] 


GTK+ uses UTF-8 encoded strings for all text. This means that if you call a method that returns a string 
you will always obtain an instance of the st r type. The same applies to methods that expect one or more 
strings as parameter, they must be UTF-8 encoded. However, for convenience PyGObject will 
automatically convert any unicode instance to st r if supplied as argument: 


>>> from gi.repository import Gtk 

>>> label = Gtk.Label () 

>>> unicode_string = u"Fulu00dfb1u00e41le" 
>>> label.set_text (unicode_string) 

>>> txt = label.get_text () 

>>> type(txt), txt 

(<type 'str'>, 'Fulxc31x9fbhxc31xa4l1le'”) 


>>> txt == unicode_string 
_ main_ _:1: UnicodeWarning: Unicode equal comparison failed to convert 
both arguments to Unicode -— interpreting them as being unequal 


False 


Note the warning at the end. Although we called|Gtk. Label. set_text () [with a unicode instance 
as argument, |Gtk . Label ..get_text () [will always return a str instance. Accordingly, txt and 
unicode_string are not equal. 


This is especially important if you want to internationalize your program using You have to make 
sure that gettext will return UTF-8 encoded 8-bit strings for all languages. In general it is recommended to 
not use unicode objects in GTK+ applications at all and only use UT'F-8 encoded str objects since 
GTK+ does not fully integrate with unicode objects. Otherwise, you would have to decode the return 
values to Unicode strings each time you call a GTK+ method: 


>>> txt = label.get_text () .decode ("utf-8") 


>>> txt == unicode_string 
True 


4.3. Python 


4.3.1. Python 3.xás Unicode supporfA1] 


Since Python 3.0, all strings are stored as Unicode in an instance of the st r type. Encoded strings on the 
other hand are represented as binary data in the form of instances of the bytes type. Conceptually, str 
refers to text, whereas bytes refers to data. Use str .encode () to go from str to bytes, and 
bytes.decode () to go from bytes to str. 


In addition, it is no longer possible to mix Unicode strings with encoded strings, because it will result in a 
TypeError: 


>>> text = "Fulu00dfb1u00e41le" 

>>> data = b" sind rund" 

>>> text + data 

Traceback (most recent call last): 

File "<stdin>", line 1, in <module> 

TypeError: Can't convert 'bytes' object to str implicitly 
>>> text + data.decode ("utf-8") 

"FuAbAnlle sind rund” 

>>> text.encode ("utf-8") + data 

b'Fuixc3Nx9fb1xc31xa4l1le sind rund' 


4.3.2. Unicode in GTK+Á9] 


As a consequence, things are much cleaner and consistent with Python 3.x, because PyGObject will 
automatically encode/decode to/from UTF-8 1f you pass a string to a method or a method returns a string. 
Strings, or text, will always be represented as instances of str only: 


>>> from gi.repository import Gtk 
>>> label = Gtk.Label () 

>>> text = "Fulu00dfb1u00e41le" 
>>> label.set_text (text) 

>>> txt = label.get_text () 

>>> type(txt), txt 

(<class 'str'>, 'FuAbAnlle') 

>>> txt == text 

True 


4.4. ReferencesÁJ] 
Whatás new in Python 3.0|describes the new concepts that clearly distinguish between text and data. 


The|jUnicode HOWTOJ|discusses Python 2.xás support for Unicode, and explains various problems that 
people commonly encounter when trying to work with Unicode. 


The|Unicode HOWTO for Python 3.x|discusses Unicode support in Python 3.x. 
UTF-8 encoding table and Unicode characters|contains a list of Unicode code points and their respective 


UTF-8 encoding. 
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6. Layout ContainersÁA] 


While many GUI toolkits require you to precisely place widgets in a window, using absolute positioning, 
GTK+ uses a different approach. Rather than specifying the position and size of each widget in the 
window, you can arrange your widgets in rows, columns, and/or tables. The size of your window can be 
determined automatically, based on the sizes of the widgets 1t contains. And the sizes of the widgets are, in 
turn, determined by the amount of text they contain, or the minimum and maximum sizes that you specify, 
and/or how you have requested that the available space should be shared between sets of widgets. You can 
perfect your layout by specifying padding distance and centering values for each of your widgets. GTK+ 
then uses all this information to resize and reposition everything sensibly and smoothly when the user 
manipulates the window. 


GTK+ arranges widgets hierarchically, using containers. They are invisible to the end user and are 
inserted into a window, or placed within each other to layout components. There are two flavours of 
containers: single-child containers, which are all descendants of|[Gtk . Bin| and multiple-child containers, 


which are descendants of|Gtk. Container| The most commonly used are vertical or horizontal boxes 
(Gt k. Box) and grids (6tk . Grial). 


6.1. BoxesA Y] 


Boxes are invisible containers into which we can pack our widgets. When packing widgets into a 
horizontal box, the objects are inserted horizontally from left to right or right to left depending on whether 


Gtk.Box.pack_start ()|or[ctk.Box.pack_enad () lis used. In a vertical box, widgets are packed 


from top to bottom or vice versa. You may use any combination of boxes inside or beside other boxes to 
create the desired effect. 


6.1.1. ExampldAY] 


Letás take a look at a slightly modified version of the extended example with two buttons. 


Hello World  X 


Hello Goodbye 


dl import gi 

2 

3 gi.require_version("Gtk", "3.0") 

4 from gi.repository import Gtk 

a 

6 

El class MyWindow(Gtk.Window) : 

8 def __ init__ (self): 

9 super ().__init__(title="Hello World") 
10 
11 self.box = Gtk.Box (spacing=6) 
12 self.add (self .box) 
13 
14 self.buttonl = Gtk.Button (label="Hello") 
15 self.buttonl.connect ("clicked", self.on_buttonl1_clicked) 
16 self.box.pack_start (self.buttonl, True, True, 0) 
17 

18 self.button2 = Gtk.Button (label="Goodbye") 

19 self .button2.connect ("clicked", self.on_button2_clicked) 
20 self.box.pack_start (self.button2, True, True, 0) 
2d 
22 def on_button1l_clicked (self, widget): 
23 print ("Hello") 
24 
25 def on_button2_clicked (self, widget): 
26 print ("Goodbye") 
2 
28 
29 win = MyWindow () 

30 win.connect ("destroy", Gtk.main_quit) 

31 win.show_all () 

32 Gtk.main () 


First, we create a horizontally orientated box container where 6 pixels are placed between children. This 
box becomes the child of the top-level window. 


self.box = Gtk.Box (spacing=6) 
self.add (self .box) 


Subsequently, we add two different buttons to the box container. 


self.buttonl = Gtk.Button (label="Hello") 
self.buttonl.connect ("clicked", self.on_buttonl_clicked) 
self.box.pack_start (self .buttonl, True, True, 0) 


self.button2 = Gtk.Button (label="Goodbye") 
self.button2.connect ("clicked", self.on_button2_clicked) 
self.box.pack_start (self .button2, True, True, 0) 


While with[Gtk.Box.pack_start () [widgets are positioned from left to right, 
Gtk.Box.pack_enad () [positions them from right to left. 


6.2. GridAJ] 


Gtk.Gridlis a container which arranges its child widgets in rows and columns, but you do not need to 


specify the dimensions in the constructor. Children are added using|[Gtk . Grid.attach ()| They can 
span multiple rows or columns. The|6tk .Grid.attach () [method takes five parameters: 


1. The child parameter is the[Gtk . Widget |to add. 


2. left is the column number to attach the left side of child to. 
3. top Indicates the row number to attach the top side of child to. 


4. width and height indicate the number of columns that the child will span, and the number of 
rows that the child will span, respectively. 


It is also possible to add a child next to an existing child, using[6tk.Grid.attach_next_to() 


which also takes five parameters: 


1. childis thejetk . Widget|to add, as above. 


2. siblingis an existing child widget of sel f (a[6tk . Gridlinstance) or None. The child widget 
will be placed next to sibling, or if siblingis None, at the beginning or end of the grid. 


3. sideisaj6tk.PositionTypelindicating the side of sibling that child is positioned next to. 


4. width and height indicate the number of columns and rows the child widget will span, 
respectively. 


Finally, [stk . Gri dlcan be used like alctk . Box]by just using Gtk.Grid.adad (), which will place 


children next to each other in the direction determined by the áorientationá property (defaults to 


[6tx Orientation HORIZONTAL). 
6.2.1. ExampleAJ] 


Grid Example 


Button 1 Button 2 


Button 4 
Button 3 
Button 5 Button 6 


import gi 
gi.require_version("Gtk", "3.0") 


from gi.repository import Gtk 


class GridWindow(Gtk.Window) : 
def __init__ (self): 


0 J0 Us WNROwOoO Jocs yn Aa 


super ().__init_ _(title="Grid Example") 
buttonl = Gtk.Button(label="Button 1") 
button2 = Gtk.Button (label="Button 2") 
button3 = Gtk.Button(label="Button 3") 
button4 = Gtk.Button (label="Button 4") 
button5 = Gtk.Button(label="Button 5") 
button6 = Gtk.Button (label="Button 6") 
19 grid = Gtk.Grid() 
20 grid.add (buttonl) 
21 grid.attach(button2, 1, 0, 2, 1) 
22 grid.attach_next_to(button3, buttonl, Gtk.PositionType.BOTTOM, 1, 2) 
23 grid.attach_next_to(button4, button3, Gtk.PositionType.RIGHT, 2, 1) 
24 grid.attach(button5, 1, 2, 1, 1) 
2D grid.attach_next_to(button6, button5, Gtk.PositionType.RIGHT, 1, 1) 
26 
27 self.add (grid) 
28 
29 
30 win = GridWindow () 
31 win.connect ("destroy", Gtk.main_quit) 
EA win.show_all () 
33 Gtk.main () 


6.3. ListBoxA 


AlGtk.ListBox]is a vertical container that contains[Gtk . ListBoxRow|children. These rows can be 


dynamically sorted and filtered, and headers can be added dynamically depending on the row content. It 
also allows keyboard and mouse navigation and selection like a typical list. 


Using|Gtk . ListBox]is often an alternative to[stk. TreeView] especially when the list content has a 


more complicated layout than what is allowed by a[6tk.Cel1Renderer| or when the content is 
interactive (e.g. has a button in it). 


Although a|[Gtk . ListBox|must have only|[Gtk . ListBoxRow|children, you can add any kind of 
widget to it via[etk. Container. add () [and ajetk . ListBoxRow|widget will automatically be 


inserted between the list and the widget. 


6.3.1. ExampleAJ] 


ListBox Demo 


Automatic Date € Time 
Requires internet access 


Enable Automatic Update 


Date Format 


Is 
ListBox 
sorted 

This 


AM/PM vw 


import gi 


gi.require_version("Gtk", "3.0") 
from gi.repository import Gtk 


class ListBoxRowWithData (Gtk.ListBoxRow) 


def __init__ (self, data): 
super ().__init__() 
self.data = data 
self.add(Gtk.Label (label=data)) 


class ListBoxWindow (Gtk.Window) : 


win 
win 
win 
Gtk 


def __init__ (self): 


super ().__init__(title="ListBox Demo") 


self.set_border_width(10) 


box_outer = Gtk.Box(orientation=Gtk.Orientation.VERTICAL, 


self .add (box_outer) 


listbox = Gtk.ListBox() 


listbox.set_selection_mode (Gtk.SelectionMode.NONE) 
box_outer.pack_start (listbox, True, 


row = Gtk.ListBoxRow () 


hbox = Gtk.Box(orientation=Gtk.Orientation.HORIZONTAL, 


row.add (hbox) 


vbox = Gtk.Box(orientation=Gtk.Orientation.VERTICAL) 


hbox.pack_start (vbox, True, True, 0) 


label1l 
label2 


" 


switch = Gtk.Switch() 


True, 


0) 
0) 


switch.props.valign = Gtk.Align.CENTER 


hbox.pack_start (switch, False, 
listbox.add (row) 


row = Gtk.ListBoxRow () 


hbox = Gtk.Box(orientation=Gtk.Orientation.HORIZONTAL, 


row.add (hbox) 


label = Gtk.Label (label="Enable Automatic Update", 


check = Gtk.CheckButton () 


True, 


hbox.pack_start (label, True, True, 0) 


hbox.pack_start (check, False, True, 


listbox.add (row) 


row = Gtk.ListBoxRow () 


hbox = Gtk.Box(orientation=Gtk.Orientation.HORIZONTAL, 


row.add (hbox) 


label = Gtk.Label (label="Date Format", 


combo = Gtk.ComboBoxText () 
combo.insert (0, "0", "24-hour") 
combo.insert (1, "1", "AM/PM") 


hbox.pack_start (label, True, True, 0) 


hbox.pack_start (combo, False, True, 


listbox.add (row) 


listbox_2 = Gtk.ListBox() 


0) 


0) 


0) 


xalign=0) 


0) 


Gtk.Label (label="Automatic Date € Time", 
Gtk.Label (label="Requires internet access", 
vbox.pack_start (label1l, True, True, 
vbox.pack_start (label2, True, True, 


items = "This is a sorted ListBox Fail".split () 


for item in items: 


listbox_2.add (ListBoxRowWithData (item) ) 


def sort_func(row_1, row_2, data, 
return row_1.data.lower() > row_2.data.lower ( 


def filter_func(row, data, notify _destroy): 


return False if row.data == 


listbox_2.set_sort_func(sort_func, 
listbox_2.set_filter_func(filter_func, 


"Fail" 


def on_row_activated(listbox_widget, 


print (row.data) 


listbox_2.connect ("row-activated", 


box_outer.pack_start (listbox_2, 
listbox_2.show_all () 


= ListBoxWindow () 

.connect ("destroy", Gtk.main_quit) 
.show_all () 

.main () 


True, 


None, 


else True 


None, 


row): 


True, 


notify_destroy) 


False) 
False) 


on_row_activated) 


0) 


spacing=6) 


spacing=50) 


spacing=50) 


spacing=50) 


6.4. Stack and StackSwitcher]AJ] 


A|Gtk. Stack]is a container which only shows one of its children at a time. In contrast to 
Gtk.Notebook]||Gtk.Stack|does not provide a means for users to change the visible child. Instead, 
the[6tk. StackSwitcher|widget can be used with|[6tk . Stackjto provide this functionality. 


Transitions between pages can be animated as slides or fades. This can be controlled with 
Gtk.Stack.set_transition type ()| These animations respect the ¿gtk-enable-animationsá 
setting. 


Transition speed can be adjusted with[Gtk.Stack.set_transition_ duration () 
The|Gtk . StackSwitcher|widget acts as a controller for ajGtk. Stack]! 1t shows a row of buttons to 


switch between the various pages of the associated stack widget. 
All the content for the buttons comes from the child properties of the|Gtk. Stack 


Itis possible to associate multiple widgets with the same[ct k . St ack] widget. 
6.4.1. ExampleAJ] 


Stack Demo 


Check Button A label 


Click me! 


import gi 


gi.require_version("Gtk", "3.0") 
from gi.repository import Gtk 


class StackWindow(Gtk.Window) : 
def __init__ (self): 
super ().__init__(title="Stack Demo") 
self.set_border_width (10) 


vbox = Gtk.Box(orientation=Gtk.Orientation.VERTICAL, spacing=6) 
self.add (vbox) 


stack = Gtk.Stack() 
stack.set_transition _type(Gtk.StackTransitionType.SLIDE_LEFT_RIGHT) 
stack.set_transition_duration(1000) 
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19 checkbutton = Gtk.CheckButton (label="Click me!") 
20 stack.add_titled(checkbutton, "check", "Check Button") 
21 

22 label = Gtk.Label () 

23 label.set_markup ("<big>A fancy label</big>") 

24 stack.add_titled(label, "label", "A label") 

25 

26 stack_switcher = Gtk.StackSwitcher () 

Zl stack_switcher.set_stack (stack) 

28 vbox.pack_start (stack_switcher, True, True, 0) 
29 vbox.pack_start (stack, True, True, 0) 

30 

31 

A win = StackWindow () 

33 win.connect ("destroy", Gtk.main_quit) 

34 win.show_all() 

39 Gtk.main () 


6.5. HeaderBar[AJ] 
A is similar to a horizontal[Gt k . Box] it allows to place children at the start or the 


end. In addition, 1t allows a title to be displayed. The title will be centered with respect to the width of the 
box, even if the children at either side take up different amounts of space. 


Since GTK+ now supports Client Side Decoration, a[6tk . HeaderBar|jcan be used in place of the title 


bar (which is rendered by the Window Manager). 


A|Gtk. HeaderBar]is usually located across the top of a window and should contain commonly used 


controls which affect the content below. They also provide access to window controls, including the close 
window button and window menu. 


6.5.1. ExampldAY] 


HeaderBar example Y 


import gi 


gi.require_version("Gtk", "3.0") 
from gi.repository import Gtk, Gio 


class HeaderBarWindow(Gtk.Window) : 
def __init_ (self): 
super().__init__(title="HeaderBar Demo") 
self.set_border_width (10) 
self.set_default_size(400, 200) 


hb = Gtk.HeaderBar () 
hb.set_show_close_button (True) 
hb.props.title = "HeaderBar example" 
self.set_titlebar (hb) 
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button = Gtk.Button () 


19 icon = Gio.ThemedIcon (name="mail-send-receive-symbolic") 

20 image = Gtk.Image.new_from_gicon(icon, Gtk.IconSize.BUTTON) 
21 button.add (image) 

2 hb.pack_end (button) 

23 

24 box = Gtk.Box(orientation=Gtk.Orientation.HORIZONTAL) 

25 Gtk.StyleContext .add_class (box.get_style_context (), "linked") 


button = Gtk.Button () 
button.adad ( 
Gtk.Arrow(arrow_type=Gtk.ArrowType.LEFT, shadow_type=Gtk.ShadowType.NONE) 
) 
box.add (button) 


button = Gtk.Button.new_from_icon_name ("pan-end-symbolic", Gtk.IconSize.MENU) 
box.add (button) 


hb.pack_start (box) 


self .add(Gtk.TextView()) 
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40 
41 win = HeaderBarWindow () 
42 win.connect ("destroy", Gtk.main_quit) 
43 win.show_all () 
44 Gtk.main () 
6.6. FlowBoxAJ] 
Note 


This example requires at least GTK+ 3.12. 


A|Gtk.FlowBoxjis a container that positions child widgets in sequence according to its orientation. 


For instance, with the horizontal orientation, the widgets will be arranged from left to right, starting a new 
row under the previous row when necessary. Reducing the width in this case will require more rows, so a 
larger height will be requested. 


Likewise, with the vertical orientation, the widgets will be arranged from top to bottom, starting a new 
column to the right when necessary. Reducing the height will require more columns, so a larger width will 
be requested. 


The children of a[ctk . F1owBox]can be dynamically sorted and filtered. 


Although a|[Gtk . F1owBox|must have only|[Gtk . FlowBoxChi l a|children, you can add any kind of 
widget to it via[etk. Container. add () | and a[ctk.F1lowBoxChi ld|widget will automatically be 


inserted between the box and the widget. 


6.6.1. ExampldAY] 


Flow Box 


ple Flovel 


import gi 


gi.require_version("Gtk", "3.0") 
from gi.repository import Gtk, Gdk 


class FlowBoxWindow(Gtk.Window) : 


win 
win 
win 
Gtk 


def _init_ (self): 
super().__init__(title="FlowBox Demo") 
self.set_border_width (10) 
self.set_default_size(300, 250) 


header = Gtk.HeaderBar (title="Flow Box") 
header.set_subtitle ("Sample FlowBox app") 


header .props.show_close_button = True 


self.set_titlebar (header) 


scrolled = Gtk.ScrolledWindow() 
scrolled.set_policy (Gtk.PolicyType.NEVER, Gtk.PolicyType. AUTOMATIC) 


flowbox = Gtk.FlowBox () 
flowbox.set_valign(Gtk.Align.START) 
flowbox.set_max_children_per_line(30) 
flowbox.set_selection_mode (Gtk.SelectionMode NONE) 


self.create_flowbox (£lowbox) 
scrolled. add (£lowbox) 


self .add(scrolled) 
self.show_all () 


def on_draw(self, widget, cr, data): 
context = widget .get_style_context () 


width = widget.get_allocated width () 
height = widget.get_allocated_height () 
Gtk.render_background (context, cr, 0, 0, width, height) 


r, 9, b, a = data["color"] 
cr.set_source_rgba(r, g, b, a) 
cr.rectangle(0, 0, width, height) 
cr.fi11() 


def color_swatch_new(self, str_color): 
rgba = Gdk.RGBA () 
rgba.parse (str_color) 


button = Gtk.Button () 


area = Gtk.DrawingArea () 
area.set_size_request (24, 24) 
area.connect ("draw", self.on_draw, ("color": rgba)) 


button. add (area) 
return button 


def create_flowbox (self, flowbox): 
colors = [ 

"AliceBlue", 
"AntiqueWhite", 
"AntiqueWhitel", 
"AntiqueWhite2", 
"AntiqueWhite3", 
"AntiqueWhite4", 
"aqua", 
"aquamarine", 
"aquamarinel”, 
"aquamarine2" 
"aquamarine3”, 
"aquamarined", 
"azure", 
"azurel”, 
"azure2”, 
"azure3”, 
"azure4”, 
"beige", 
"bisque", 
"bisquel" 


"bisque3", 
"bisque4", 
"black", 
"BlanchedAlmond" 
"blue" 
"bluel", 


"blue3", 
"blue4", 
"BlueViolet", 
"brown", 
"brown1", 
"brown2", 
"brown3", 
"brown4", 
"burlywood", 
"burlywood1", 
"burlywood2", 
"burlywood3", 
"burlywood4", 
"CadetBlue", 
"CadetBluel", 
"CadetBlue2", 
"CadetBlue3", 
"CadetBlue4", 
"chartreuse", 
"chartreusel" 
"chartreuse2" 
"chartreuse3", 
"chartreused", 
"chocolate", 
"chocolatel", 
"chocolate2", 
"chocolate3", 
"chocolate4", 
"coral", 
"coral1”, 
"coral2", 
"coral3", 
"coral4", 


for color in colors: 
button = self.color_swatch_new(color) 
flowbox.add (button) 


= FlowBoxWindow () 

.connect ("destroy", Gtk.main_quit) 
.«show_all () 

.main () 


6.7. NotebookKA J] 


The|Gtk . Notebook|widget is a[etk. Container|whose children are pages that can be switched 


between using tab labels along one edge. 


There are many configuration options for GtkNotebook. Among other things, you can choose on which 


edge the tabs appear (see|Gtk .. Notebook.set_tab_pos () ), whether, if there are too many tabs to fit 


the notebook should be made bigger or scrolling arrows added (see 
Gtk.Notebook.set_scrollable ()), and whether there will be a popup menu allowing the users 


to switch pages (see[Gtk. Notebook .popup_enable ()|[6tk.Notebook.popup_disable ()|). 
6.7.1. ExampleAJ] 


Simple Notebook Example X 


Plain Title << 


Default Page! 


1 import gi 

2 

3 gi.require _version("Gtk", "3.0") 

4 from gi.repository import Gtk 

ha) 

6 

7 class MyWindow(Gtk.Window) : 

8 def __init__ (self): 

9 super()._ _init__(title="Simple Notebook Example") 

10 self.set_border_width (3) 

11 

12 self.notebook = Gtk.Notebook () 

13 self.add(self.notebook) 

14 

15 self.pagel = Gtk.Box() 

16 self.pagel.set_border_width(10) 

17 self .pagel.add(Gtk.Label (label="Default Page!")) 

18 self.notebook.append_page (self .pagel, Gtk.Label (label="Plain Title")) 
19 
20 self.page2 = Gtk.Box() 
21 self.page2.set_border_width(10) 
22 self.page2.add(Gtk.Label (label="A page with an image for a Title.")) 
23 self.notebook.append_page ( 
24 self.page2, Gtk.Image.new_from_icon_name ("help-about", Gtk.IconSize.MENU) 
25 ) 


win = MyWindow () 

win.connect ("destroy", Gtk.main_quit) 
win.show_all () 

Gtk.main () 
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7. LabelAJ] 


Labels are the main method of placing non-editable text in windows, for instance to place a title next to a 
Gtk .Entry|widget. You can specify the text in the constructor, or later with the 


Gtk.Label.set_text ()/Jor[Gtk.Label.set_markup () [methods. 


The width of the label will be adjusted automatically. You can produce multi-line labels by putting line 
breaks (A41ná) in the label string. 


Labels can be made selectable with|Gtk. Label. set_selectable ()| Selectable labels allow the 


user to copy the label contents to the clipboard. Only labels that contain useful-to-copy information á such 
as error messages á should be made selectable. 


The label text can be justified using the[Gtk . Label. set_Justify () [method. The widget is also 
capable of word-wrapping, which can be activated with|[Gtk.Label.set_line_wrap() 


Gtk. Label |support some simple formatting, for instance allowing you to make some text bold, colored, 


or larger. You can do this by providing a string to[Gtk. Label. set_markup ()] using the Pango 
Markup syntax|1| For instance, <b>bold text</b> and <s>strikethrough text</s>. In 
addition, supports clickable hyperlinks. The markup for links is borrowed from HTML, 
using the a with href and title attributes. GTK+ renders links similar to the way they appear in web 
browsers, with colored, underlined text. The title attribute is displayed as a tooltip on the link. 


label.set_markup ("Go to <a href=1"https://www.gtk.orgXi" " 
"title=1X"0ur websitel">GTK+ website</a> for more") 


Labels may contain mnemonics. Mnemonics are underlined characters in the label, used for keyboard 
navigation. Mnemonics are created by providing a string with an underscore before the mnemonic 


character, such as 4_Fileá, to the functions|Gtk. Label .new_with_mnemonic ()|or 
Gtk.Label.set_text_with_mnemonic ()| Mnemonics automatically activate any activatable 
widget the label is inside, such as a[ctk . Butt onj if the label is not inside the mnemonicás target widget, 


you have to tell the label about the target using[Gtk . Label. set_mnemonic_widget () 


TÁ ExampleAY] 


Label Example 


This is a normal label 


This is a left-justified label. 
With multiple lines. 


This is a right-justified label. 
With multiple lines. 


Text can be small, Dig, bold, ¡talic and even point to 
somewhere in the internets. 


Press Alt + P to select button to the right 


This is an example of a line-wrapped 
label. Itshould not be taking up the 
entire width allocated to it, but 
automatically wraps the words to fit. 

It supports multiple paragraphs 
correctly, and correctly adds many 
extra spaces. 


This is an example of a line-wrapped 
filled label. It should be taking up the 
entire width allocated to it. Here ¡ 
a sentence to prove my point. Here ¡ 
another sentence. Here comes the sun 
do de do de do. 
This is a new paragraph. 

This is another newer, longer, bette 
paragraph. It is coming to an end 
unfortunately. 


Click at your own risk 


import gi 


gi.require_version("Gtk", "3.0") 
from gi.repository import Gtk 


class LabelWindow(Gtk.Window) : 
def __init__ (self): 
super().__init__ (title= 


Label Example") 


hbox = Gtk.Box(spacing=10) 

hbox.set_homogeneous (False) 

vbox_left = Gtk.Box(orientation=Gtk.Orientation.VERTICAL, spacing=10) 
vbox_left.set_homogeneous (False) 

vbox_right = Gtk.Box(orientation=Gtk.Orientation.VERTICAL, spacing=10) 
vbox_right.set_homogeneous (False) 


hbox.pack_start (vbox_left, True, True, 0) 
hbox.pack_start (vbox_right, True, True, 0) 


label = Gtk.Label (label="This is a normal label") 
vbox_left.pack_start (label, True, True, 0) 


label = Gtk.Label () 

label.set_text ("This is a left-justified label.1inWith multiple lines.") 
label.set_justify(Gtk.Justification.LEFT) 

vbox_left.pack_start (label, True, True, 0) 


label = Gtk.Label ( 

label="This is a right-justified label.inWith multiple lines." 
) 
label.set_justify(Gtk.Justification.RIGHT) 
vbox_left.pack_start (label, True, True, 0) 


label = Gtk.Label ( 
label="This is an example of a line-wrapped label. It " 
"should not be taking up the entire ” 
"width allocated to it, but automatically " 
"wraps the words to fit.In" 
ps It supports multiple paragraphs correctly, " 
"and correctly adds " 
"many extra spaces. " 
) 
label.set_line_wrap(True) 
label.set_max_width_chars (32) 
vbox_right.pack_start (label, True, True, 0) 


label = Gtk.Label ( 
label="This is an example of a line-wrapped, filled label. " 
"It should be taking " 
"up the entire width allocated to it. " 
"Here is a sentence to prove " 
"my point. Here is another sentence. " 
"Here comes the sun, do de do de do.In" 
* This is a new paragraph.In" 
sel This is another newer, longer, better " 
"paragraph. It is coming to an end, " 
"unfortunately." 
) 
label.set_line_wrap(True) 
label.set_justify(Gtk.Justification.FILL) 
label.set_max_width_chars (32) 
vbox_right.pack_start (label, True, True, 0) 


label = Gtk.Label () 

label.set_markup ( 
"Text can be <small>small1</small1>, <big>big</big>, " 
"<b>bold</b>, <i>italic</i> and even point to " 
"somewhere in the <a href="https://www.gtk.org" ” 
'title="Click to find out more">internets</a>.'” 

) 

label.set_line_wrap(True) 

label.set_max_width_chars (48) 

vbox_left.pack_start (label, True, True, 0) 


label = Gtk.Label.new_with_mnemonic ( 

"_Press Alt + P to select button to the right" 
) 
vbox_left.pack_start (label, True, True, 0) 
label.set_selectable (True) 


button = Gtk.Button(label="Click at your own risk") 
label.set_mnemonic_widget (button) 
vbox_right.pack_start (button, True, True, 0) 


self .add (hbox) 


window = LabelWindow () 

window.connect ("destroy", Gtk.main_quit) 
window.show_all () 

Gtk.main () 
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$. EntryAYJ] 


Entry widgets allow the user to enter text. You can change the contents with the 


Gtk.Entry.set_text () |[method, and read the current contents with the 


Gtk.Entry.get_text () [method. You can also limit the number of characters the Entry can take by 


calling[Gtk.Entry.set_max_length () 


Occasionally you might want to make an Entry widget read-only. This can be done by passing False to 
the Gtk.Entry.set_editable () method. 


Entry widgets can also be used to retrieve passwords from the user. It is common practice to hide the 
characters typed into the entry to prevent revealing the password to a third party. Calling 


Gtk.Entry.set_visibility ()|with False will cause the text to be hidden. 


Gtk.EntryJjhas the ability to display progress or activity information behind the text. This is similar to 
Gtk.ProgressBar|widget and is commonly found in web browsers to indicate how much of a page 
download has been completed. To make an entry display such information, use 


Gtk.Entry.set_progress_fraction ()||¡Gtk.Entry.set_progress_pulse_step()|or 


Gtk.Entry.progress_pulse() 


Additionally, an Entry can show icons at either side of the entry. These icons can be activatable by 
clicking, can be set up as drag source and can have tooltips. To add an icon, use 


Gtk.Entry.set_icon_from_icon_name ()|or one of the various other functions that set an icon 


from an icon name, a pixbuf, or icon theme. To set a tooltip on an icon, use 
Gtk.Entry.set_icon_tooltip_text ()|or the corresponding function for markup. 


8.1. ExampldAY] 


Entry Demo 


Hello World 


Y Editable ¡W Visible Pulse Icon 
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import gi 


gi.require_version("Gtk", "3.0") 
from gi.repository import Gtk, GLib 


class EntryWindow(Gtk.Window) : 


win 


def 


def 


def 


def 


def 


def 


_ init_ (self): 
super().__init_ _(title="Entry Demo") 
self.set_size_request (200, 100) 


self.timeout_id = None 


vbox = Gtk.Box(orientation=Gtk.Orientation.VERTICAL, spacing=6) 
self .add (vbox) 


self.entry = Gtk.Entry () 
self.entry.set_text ("Hello World") 
vbox.pack_start (self.entry, True, True, 0) 


hbox = Gtk.Box (spacing=6) 
vbox.pack_start (hbox, True, True, 0) 


self.check_editable = Gtk.CheckButton (label="Editable") 
self.check_editable.connect ("toggled", self.on_editable_toggled) 
self.check_editable.set_active(True) 

hbox.pack_start (self.check_editable, True, True, 0) 


self.check_visible = Gtk.CheckButton (label="Visible") 
self.check_visible.connect ("toggled", self.on_visible_toggled) 
self.check_visible.set_active(True) 

hbox.pack_start (self.check_visible, True, True, 0) 


self.pulse = Gtk.CheckButton (label="Pulse") 
self.pulse.connect ("toggled", self.on_pulse_toggled) 
self.pulse.set_active (False) 

hbox.pack_start (self.pulse, True, True, 0) 


self.icon = Gtk.CheckButton (label="Icon") 
self.icon.connect ("toggled", self.on_icon_toggled) 
self.icon.set_active (False) 

hbox.pack_start (self.icon, True, True, 0) 


on_editable_toggled(self, button): 
value = button.get_active() 
self.entry.set_editable (value) 


on_visible_toggled(self, button): 
value = button.get_active() 
self.entry.set_visibility (value) 


on_pulse_toggled (self, button): 
if button.get_active(): 
self.entry.set_progress_pulse_step(0.2) 
+ Call self.do_pulse every 100 ms 
self.timeout_id = GLib.timeout_add(100, self.do_pulse, None) 
else: 
+ Don't call self.do_pulse anymore 
GLib.source_remove (self .timeout_id) 
self.timeout_id = None 
self.entry.set_progress_pulse_step(0) 


do_pulse (self, user_data): 
self.entry.progress_pulse () 
return True 


on_icon_toggled(self, button): 
if button.get_active(): 
icon_name = "system-search-symbolic" 
else: 
icon_name = None 
self.entry.set_icon_from_icon_name (Gtk.EntryIlconPosition.PRIMARY, 


= EntryWindow () 

win.connect ("destroy", Gtk.main_quit) 
win.show_all () 

Gtk.main () 
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e —|Edit on GitHub 


9. Button WidgetgA Y 
9.1. ButtonAJ] 


The Button widget is another commonly used widget. It is generally used to attach a function that is called 
when the button is pressed. 


The widget can hold any valid child widget. That is it can hold most any other standard 
The most commonly used child is the 

Usually, you want to connect to the buttonás áclickedá signal which is emitted when the button has been 
pressed and released. 


9.1.1. ExampldAY] 


Button Demo 


Click Me Open 


import gi 


gi.require_version("Gtk", "3.0") 
from gi.repository import Gtk 


class ButtonWindow (Gtk.Window) : 
def __init__ (self): 
super ().__init__(title="Button Demo") 
self.set_border_width (10) 


hbox = Gtk.Box(spacing=6) 
self.add (hbox) 


button = Gtk.Button.new_with_label ("Click Me") 
button.connect ("clicked", self.on_click_me_clicked) 
hbox.pack_start (button, True, True, 0) 
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19 button = Gtk.Button.new_with_mnemonic ("_Open") 
20 button.connect ("clicked", self.on_open_clicked) 
21 hbox.pack_start (button, True, True, 0) 

22 

23 button = Gtk.Button.new_with_mnemonic("_Close") 
24 button.connect ("clicked", self.on_close_clicked) 
2D hbox.pack_start (button, True, True, 0) 

26 

27 def on_click_me _clicked(self, button): 

28 print (' "Click me" button was clicked') 

29 

30 def on_open_clicked(self, button): 

31 print (' "Open" button was clicked') 

32 

33 def on_close_clicked (self, button): 

34 print ("Closing application") 

35 Gtk.main_quit () 

36 

37 

38 win = ButtonWindow () 

39 win.connect ("destroy", Gtk.main_quit) 

40 win.show_all () 

41 Gtk.main () 


9.2. ToggleButtonAJ] 
A is very similar to a normal[Gtk . Button] but when clicked they remain 


activated, or pressed, until clicked again. When the state of the button is changed, the átoggledá signal is 
emitted. 


To retrieve the state of the[ctk . ToggleButton| you can use the 
Gtk.ToggleButton.get_active () |method. This returns True if the button is idowná. You can 


also set the toggle buttonás state, with[Gtk . ToggleButton.set_active ()| Note that, 1f you do 


this, and the state actually changes, it causes the átoggledá signal to be emitted. 


9.2.1. ExampleAJ] 


ToggleButton Demo X 


Button 1 Button 2 


Y import gi 

2 

3 gi.require_version("Gtk", "3.0") 

4 from gi.repository import Gtk 

J 

6 

d class ToggleButtonWindow(Gtk.Window) : 

8 def __ init__ (self): 

9 super ().__init_ _(title="ToggleButton Demo") 
10 self.set_border_width(10) 

11 

12 hbox = Gtk.Box(spacing=6) 

13 self.add (hbox) 

14 

15 button = Gtk.ToggleButton (label="Button 1") 
16 button.connect ("toggled", self.on_button_toggled, "1") 
E hbox.pack_start (button, True, True, 0) 

18 

19 button = Gtk.ToggleButton(label="B_utton 2", use_underline=True) 
20 button.set_active(True) 
21 button.connect ("toggled", self.on_button_toggled, "2") 
22 hbox.pack_start (button, True, True, 0) 
23 
24 def on_button_toggled (self, button, name): 
23 if button.get_active(): 
26 state = "on" 

27 else: 

28 state = "off" 

29 print ("Button", name, "was turned", state) 
30 

31 

32 win = ToggleButtonWindow () 

33 win.connect ("destroy", Gtk.main_quit) 

34 win.show_all () 

35 Gtk.main () 


9.3. CheckButtonAJ] 


[Stk . CheckBut t onlinherits from|[ctk . ToggleButton] The only real difference between the two is 
[Sex -checkbuetonfs appearance. A[SEK -CheckBueton)places a disorete[GEk. ToggleButtor] 
next to a widget, (usually a[ctk. Label). The átoggledá signal, 

[tk ToggleButton. set_act ive () Jand[6tk. ToggleButton .get_act ive () Jare inherited, 


9.4. RadioButtonAJ] 
Like checkboxes, radio buttons also inherit from[Stk. ToggleButton] but these work in groups, and 


only one[Gtk . RadioButtonjin a group can be selected at any one time. Therefore, a 
Gtk.RadioButtonjis one way of giving the user a choice from many options. 


Radio buttons can be created with one of the static methods 
Gtk.RadioButton.new_from_widget () 
Gtk.RadioButton.new_with_label_from_widget ()|or 


Gtk.RadioButton.new_with_mnemonic_from_widget () | The first radio button in a group 


will be created passing None as the group argument. In subsequent calls, the group you wish to add this 
button to should be passed as an argument. 


When first run, the first radio button in the group will be active. This can be changed by calling 


Gtk.ToggleButton.set_active () [with True as first argument. 


Changing a[6tk .. RadioButtonkhs widget group after its creation can be achieved by calling 
Gtk.RadioButton.join_group() 


9.4.1. ExampldAY] 


RadioButton Demo Xx 


e Button 1 Button 2 Button 3 
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import gi 


gi.require_version("Gtk", "3.0") 
from gi.repository import Gtk 


class RadioButtonWindow(Gtk.Window) : 


def __init__ (self): 
super ().__init__(title="RadioButton Demo") 
self.set_border_width (10) 


hbox = Gtk.Box(spacing=6) 
self.add (hbox) 


buttonl = Gtk.RadioButton.new_with_label_from_ widget (None, "Button 1") 
buttonl.connect ("toggled", self.on_button_toggled, "1") 

hbox.pack_start (buttonl, False, False, 0) 

button2 = Gtk.RadioButton.new_from_widget (button1l) 

button2.set_label ("Button 2") 

button2.connect ("toggled", self.on_button_toggled, "2") 

hbox.pack_start (button2, False, False, 0) 

button3 = Gtk.RadioButton.new_with_mnemonic_from_widget (buttonl, "B_utton 3") 
button3.connect ("toggled", self.on_button_toggled, "3") 

hbox.pack_start (button3, False, False, 0) 


def on_button_toggled(self, button, name): 
if button.get_active(): 
state = "on" 
else: 
state = "off" 
print ("Button", name, "was turned", state) 


= RadioButtonWindow () 


.connect ("destroy", Gtk.main_quit) 
.show_all () 
.main () 


9.5. LinkButtonlAJ] 
A is a[stk . Button|with a hyperlink, similar to the one used by web browsers, 


which triggers an action when clicked. It is useful to show quick links to resources. 


The URI bound to al[etk . LinkButtonjcan be set specifically using 
Gtk.LinkButton.set_uri ()| and retrieved using[Gtk.LinkButton.get_uri() 


9.5.1. ExampldAY] 


LinkButton Demo X 


Visit GTK+ Homepage 


import gi 


gi.require_version("Gtk", "3.0") 
from gi.repository import Gtk 


class LinkButtonWindow(Gtk.Window) : 
def __init__ (self): 
super ().__init__(title="LinkButton Demo") 
self.set_border_width (10) 


button = Gtk.LinkButton.new_with_label ( 
uri="https://www.gtk.org", 
label="Visit GTK+ Homepage" 

) 

self.add (button) 
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19 win = LinkButtonWindow () 

20 win.connect ("destroy", Gtk.main_quit) 
21 win.show_all() 

22 Gtk.main () 


9.6. SpinButtonAJ] 


A|Gtk. SpinButtonjis an ideal way to allow the user to set the value of some attribute. Rather than 
having to directly type a number into a[etk .Entry||[6tk. SpinButtonJallows the user to click on one 


of two arrows to increment or decrement the displayed value. A value can still be typed in, with the bonus 


that it can be checked to ensure it is in a given range. The main properties of a[Gtk . SpinButtonjare set 
through[Gtk . Adjustment 


To change the value that[6tk . SpinButtonjis showing, use[Gtk. SpinButton.set_value ()| The 


value entered can either be an integer or float, depending on your requirements, use 


Gtk.SpinButton.get_value_as_int ()|or[Gtk.SpinButton.get_value () | respectively. 


When you allow the displaying of float values in the spin button, you may wish to adjust the number of 


decimal spaces displayed by calling 


By default, |etk . SpinButtonjaccepts textual data. If you wish to limit this to numerical values only, 
call[6tk. SpinButton.set_numeric () with True as argument. 


We can also adjust the update policy of[6tk. SpinButton| There are two options here; by default the 
spin button updates the value even if the data entered is invalid. Alternatively, we can set the policy to 


only update when the value entered is valid by calling 
9.6.1. ExampldAY] 


SpinButton Demo 


+ | Numeric If Valid 


import gi 


gi.require_version("Gtk", "3.0") 
from gi.repository import Gtk 


class SpinButtonWindow (Gtk.Window) : 
def __init__ (self): 
super().__init__(title="SpinButton Demo") 
self.set_border_width (10) 


hbox = Gtk.Box (spacing=6) 
self.add (hbox) 


adjustment = Gtk.Adjustment (upper=100, step_increment=1, page_increment=10) 
self.spinbutton = Gtk.SpinButton () 

self.spinbutton.set_adjustment (adjustment) 

self.spinbutton.connect ("value-changed", self.on_value_changed) 
hbox.pack_start (self .spinbutton, False, False, 0) 


check_numeric = Gtk.CheckButton (label="Numeric") 
check_numeric.connect ("toggled", self.on_numeric_toggled) 
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23 hbox.pack_start (check_numeric, False, False, 0) 
24 

25 check_ifvalid = Gtk.CheckButton (label="If Valid") 
26 check_ifvalid.connect ("toggled", self.on_ifvalid_toggled) 
27 hbox.pack_start (check_ifvalid, False, False, 0) 
28 

29 def on_value_changed(self, scroll): 

30 print (self .spinbutton.get_value_as_int ()) 

31 

32 def on_numeric_toggled(self, button): 

33 self.spinbutton.set_numeric (button.get_active()) 
34 

39 def on_ifvalid_toggled(self, button): 

36 if button.get_active(): 

37 policy = Gtk.SpinButtonUpdatePolicy.IF_VALID 
38 else: 

39 policy = Gtk.SpinButtonUpdatePolicy.ALWAYS 
40 self.spinbutton.set_update_policy (policy) 

41 

42 

43 win = SpinButtonWindow () 

44 win.connect ("destroy", Gtk.main_quit) 

45 win.show_all () 

46 Gtk.main () 


9.7. SwitcHAY] 


A is a widget that has two states: on or off. The user can control which state should be 
active by clicking the empty area, or by dragging the handle. 


You shouldnát use the áactivateá signal on the Gtk.Switch which is an action signal and emitting it causes 
the switch to animate. Applications should never connect to this signal, but use the ánotify::activeá signal, 
see the example here below. 


9.7. ExampleAJ] 


Switch Demo 


4: import gi 

2 

3 gi.require_version("Gtk", "3.0") 

4 from gi.repository import Gtk 

5 

6 

7 class SwitcherWindow(Gtk.Window) : 

8 def __ init__ (self): 

9 super ().__init__(title="Switch Demo") 
10 self.set_border_width(10) 
11 
12 hbox = Gtk.Box(spacing=6) 
13 self.add (hbox) 
14 
15 switch = Gtk.Switch() 
16 switch.connect ("notify::active", self.on_switch_activated) 
1 switch.set_active (False) 
18 hbox.pack_start (switch, True, True, 0) 
19 
20 switch = Gtk.Switch() 
21 switch.connect ("notify::active", self.on_switch_activated) 
22 switch.set_active(True) 
23 hbox.pack_start (switch, True, True, 0) 
24 
25 def on_switch_activated(self, switch, gparam): 
26 if switch.get_active(): 
21 state = "on" 
28 else: 
29 state = "off" 

30 print ("Switch was turned", state) 

31 

32 

33 win = SwitcherWindow () 

34 win.connect ("destroy", Gtk.main_quit) 

35 win.show_all() 

36 Gtk.main () 
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10. ExpanderAJ] 


Expanders allow to dynamically hide or show information within a window or dialog. An expander can 
take a single widget that will be displayed when expanded. 


Expanders remain expanded until clicked again. When the state of an expander is changed, the áactivateá 
signal is emitted. 


An expander can be programmatically expanded or collapsed by passing True or False to 


Gtk.Expander.set_expanded () | Note that doing so causes the áactivateá signal to be emitted. 


More than one widget, such as a[Gtk . Labelland|6tk.Button| can be added by appending them to a 


10.1. ExampldÁAY] 


Expander Demo 


v This expander displays additional information 


This message is quite long, complicated even: 
- It has a list with a sublist: 
- Of 3 elements; 
- taking several lines; 
- with indentation. 


» Expand for more controls 


class 
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import gi 


Expander] 
def __init__ (self): 


super ( 


self.s 


gi.require_version("Gtk", "3.0") 
from gi.repository import Gtk 


Example (Gtk.Window) : 


).__init_ (title="Expander Demo") 


vbox = 


t_size_request (350, 100) 


Gtk.Box(orientation=Gtk.Orientation.VERTICAL, spacing=6) 


self.add (vbox) 


text_expander = Gtk.Expander ( 


) 


label="This expander displays additional information" 


19 text_expander.set_expanded (True) 

20 vbox.add (text_expander) 

21 

22 msg = """ 

23 This message is quite long, complicated even: 

24 - It has a list with a sublist: 

25 - Of 3 elements; 

26 - taking several lines; 

2h - with indentation. 

28 e 

29 details = Gtk.Label (label=msg) 

30 text_expander.add (details) 

31 

32 widget_expander = Gtk.Expander (label="Expand for more controls") 
33 vbox.add (widget_expander) 

34 

35 expander_hbox = Gtk.HBox() 

36 widget_expander.add (expander_hbox) 

37 

38 expander_hbox.add(Gtk.Label (label="Text message")) 
39 expander_hbox.add(Gtk.Button(label="Click me")) 
40 


1 
2 
3 
4 win = 
5 
6 
7 


Next|Previous 


self.s 


Expander] 
win.connect ("destroy", Gtk.main_quit) 
win.show_all () 
Gtk.main () 


how_all () 


Example () 
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11. ProgressBai]AJ] 


The|Gtk .ProgressBarlis typically used to display the progress of a long running operation. It 
provides a visual clue that processing is underway. The|6tk .ProgressBarjcan be used in two different 


modes: percentage mode and activity mode. 


When an application can determine how much work needs to take place (e.g. read a fixed number of bytes 


from a file) and can monitor its progress, it can use the[stk. ProgressBarlin percentage mode and the 


user sees a growing bar indicating the percentage of the work that has been completed. In this mode, the 


application is required to call[etk .ProgressBar.set_fraction () periodically to update the 


progress bar, passing a float between O and 1 to provide the new percentage value. 


When an application has no accurate way of knowing the amount of work to do, it can use activity mode, 
which shows activity by a block moving back and forth within the progress area. In this mode, the 


application is required to call[etk .ProgressBar .pulse () [periodically to update the progress bar. 
You can also choose the step size, with the[6tk.ProgressBar.set_pulse_step () [method. 


By default, |¡etk . ProgressBarlis horizontal and left-to-right, but you can change it to a vertical 


progress bar by using the Gtk.ProgressBar.set_orientation() method. Changing the 


direction the progress bar grows can be done using[6tk.ProgressBar.set_inverted() 
Gtk.ProgressBarican also contain text which can be set by calling 
Gtk.ProgressBar.set_text () [and[ctk.ProgressBar.set_show_text () 
11.1. ExampleAY] 


ProgressBar Demo X 


Show text 


Activity mode 


Right to Left 
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import gi 


gi.require_version("Gtk", "3.0") 
from gi.repository import Gtk, GLib 


class ProgressBarWindow(Gtk.Window) : 


win 
win 
win 
Gtk 


def __init__ (self) 


super ().__init__(title="ProgressBar Demo") 
self.set_border_width(10 


vbox = Gtk.Box(orientation=Gtk.Orientation.VERTICAL, spacing=6) 


self.add (vbox) 


self.progressbar = Gtk.ProgressBar () 
vbox.pack_start (self .progressbar, True, True, 0) 


button = Gtk.CheckButton (label="Show text") 


button.connect ("toggled", 


vbox.pack_start (button, True, 


self.on_show_text_toggled) 


True, 0) 


button = Gtk.CheckButton (label="Activity mode") 


button.connect ("toggled", 


vbox.pack_start (button, True, 


self.on_activity_mode_toggled) 


True, 0) 


button = Gtk.CheckButton (label="Right to Left") 


button.connect ("toggled", 


vbox.pack_start (button, True, 


self.timeout_id 
self.activity_mode = False 


self.on_right_to_left_toggled) 


True, 0) 


= GLib.timeout_add(50, self.on_timeout, None) 


def on_show_text_toggled(self, button): 
show_text = button.get_active() 


if show_text: 


text = "some text" 


else: 


text = None 
self.progressbar.set_text (text) 
self.progressbar.set_show_text (show_text) 


def on_activity_mode_toggled (self, 


button): 


self.activity_mode = button.get_active() 
if self.activity_mode: 
self.progressbar.pulse ( 


else: 


self .progressbar.set_fraction(0.0) 


def on_right_to_left_toggled(self, 


value = button.get_active() 
self.progressbar.set_inverted (value) 


def on_timeout (self, user_data): 


button): 


Update value on the progress bar 


if self.activity_mode: 
self .progressbar.pulse ( 


else: 
new_value 


self.progressbar.get_fraction() + 0.01 


if new_value > 1: 
new_value = 0 


self.progressbar.set_fraction(new_value) 


+ As this is a timeout function, return True so that it 
+ continues to get called 


return True 


= ProgressBarWindow () 


.Cconnect ("destroy", 
.show_all () 
.main () 


Gtk.main_quit) 
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12. Spinner]AY] 


The|Gtk . Spinner|displays an icon-size spinning animation. It is often used as an alternative to a 


GtkProgressBar for displaying indefinite activity, instead of actual progress. 


To start the animation, use[Gtk . Spinner . start ()] to stop ituse[6tx . Spinner . stop ()] 
12,1. ExampldÁY] 


Spinner X 


Stop Spinning 


Ns 


import gi 


gi.require_version("Gtk", "3.0") 
from gi.repository import Gtk 


class SpinnerAnimation(Gtk.Window) : 
def __init__ (self): 


super ().__init__(title="Spinner") 
self.set_border_width (3) 
self.connect ("destroy", Gtk.main_quit) 


self.button = Gtk.ToggleButton (label="Start Spinning") 
self .button.connect ("toggled", self.on_button_toggled) 
self.button.set_active (False) 
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self.spinner = Gtk.Spinner () 


19 

20 self.grid = Gtk.Grid() 

21 self.grid.add(self.button) 

22 self.grid.attach_next_to( 

23 self.spinner, self.button, Gtk.PositionType.BOTTOM, 1, 2 
24 ) 

25 self.grid.set_row_homogeneous (True) 

26 

27 self.add (self .grid) 

28 self.show_all () 

29 

30 def on_button_toggled (self, button): 

31 

3e if button.get_active(): 

33 self.spinner.start () 

34 self.button.set_label ("Stop Spinning") 
35 

36 else: 

31 self.spinner.stop() 

38 self.button.set_label ("Start Spinning") 
319 

40 

41 myspinner = SpinnerAnimation () 

42 


43 Gtk.main () 


12.2. Extended exampleAY] 


An extended example that uses a timeout function to start and stop the spinning animation. The 
on_timeout () function is called at regular intervals until 1t returns False, at which point the timeout 
1s automatically destroyed and the function will not be called again. 


12.2.1. ExampldA] 


Spinner Demo 


U 


Remaining: 9 


Stop timer 


import gi 


gi.require_version("Gtk", "3.0") 
from gi.repository import Gtk, GLib 


class SpinnerWindow(Gtk.Window) : 
def __init__(self, *args, **kwargs): 
super ().__init__(title="Spinner Demo") 
self.set_border_width(10) 


mainBox = Gtk.Box(orientation=Gtk.Orientation.VERTICAL, spacing=6) 
self .add (mainBox) 


self.spinner = Gtk.Spinner () 
mainBox.pack_start (self .spinner, True, True, 0) 


self.label = Gtk.Label () 
mainBox.pack_start (self .label, True, True, 0) 


Prep. 
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self.entry = Gtk.Entry() 
self.entry.set_text ("10") 
mainBox.pack_start (self .entry, True, True, 0) 


self.buttonStart = Gtk.Button (label="Start timer") 
self.buttonStart.connect ("clicked", self.on_buttonStart_clicked) 
mainBox.pack_start (self .buttonStart, True, True, 0) 


self .buttonStop = Gtk.Button (label="Stop timer") 
self .buttonStop.set_sensitive (False) 
self .buttonStop.connect ("clicked", self.on_buttonStop_clicked) 


WWNNNNNNNNNNy 
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32 mainBox.pack_start (self .buttonStop, True, True, 0) 

33 

34 self.timeout_id = None 

35 self.connect ("destroy", self.on_SpinnerWindow_destroy) 
36 

37 def on_buttonStart_clicked(self, widget, *args): 

38 """ Handles "clicked" event of buttonStart. """ 

39 self.start_timer () 

40 

41 def on_buttonStop_clicked(self, widget, *args): 


""" Handles "clicked" event of buttonStop. """ 
self.stop_timer ("Stopped from button") 


def on_SpinnerWindow_destroy (self, widget, *args): 
""" Handles destroy event of main window. """ 
+ ensure the timeout function is stopped 
if self.timeout_id: 
GLib.source_remove (self .timeout_id) 
self.timeout_id = None 
Gtk.main_quit () 


def on_timeout (self, *args, **kwargs): 
""" A timeout function. 


Return True to stop it. 
This is not a precise timer since next timeout 
is recalculated based on the current time.""" 
self.counter -= 1 
if self.counter <= 0: 

self.stop_timer ("Reached time out") 


7 0 010101000 UU ls ls ls ls ss ls 
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62 return False 

63 self.label.set_label ("Remaining: " + str(int(self.counter / 4))) 

64 return True 

65 

66 def start_timer (self): 

67 """ Start the timer. """ 

68 self .buttonStart.set_sensitive (False) 

69 self .buttonStop.set_sensitive (True) 

70 + time out will check every 250 milliseconds (1/4 of a second) 

71 self.counter = 4 * int (self.entry.get_text ()) 
self.label.set_label ("Remaining: " + str(int(self.counter / 4))) 


self.spinner.start () 
self.timeout_id = GLib.timeout_add(250, self.on_timeout, None) 


def stop_timer (self, alabeltext): 
""" Stop the timer. ' 
if self.timeout_id: 
GLib.source_remove (self .timeout_id) 
self.timeout_id = None 
self.spinner.stop() 
self .buttonStart.set_sensitive (True) 
self .buttonStop.set_sensitive (False) 
self.label.set_label (alabeltext) 


wo 0w00w00w0w%ww%IIIIIIS Y 
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87 win = SpinnerWindow () 
88 win.show_all () 
89 Gtk.main () 
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13, Tree and List WidgetdA Y 


A|Gtk.TreeViewland its associated widgets are an extremely powerful way of displaying data. They 
are used in conjunction with a[Gtk. ListStorejor[stk.TreeStorejand provide a way of displaying 


and manipulating data in many ways, including: 
e Automatic updates when data is added, removed or edited 
e Drag and drop support 
e Sorting data 
e Embedding widgets such as check boxes, progress bars, etc. 
e Reorderable and resizable columns 


e Filtering data 


With the power and flexibility of a[ctk . TreeView|comes complexity. It is often difficult for beginner 
developers to be able to utilize it correctly due to the number of methods which are required. 


13.1. The ModelAJ] 


Each has an associated|[Gtk . TreeMode1| which contains the data displayed by the 
TreeView. Each[Gtk . TreeMode 1|can be used by more than one For instance, this 
allows the same underlying data to be displayed and edited in 2 different ways at the same time. Or the 2 


Views might display different columns from the same Model data, in the same way that 2 SQL queries (or 
áviewsá) might show different fields from the same database table. 


Although you can theoretically implement your own Model, you will normally use either the 


Gtk.ListStorejor[6tk.TreeStore|model classes. [Gtk . ListStorejcontains simple rows of 


data, and each row has no children, whereas|[Gtk. TreeStorejcontains rows of data, and each row may 
have child rows. 


When constructing a model you have to specify the data types for each column the model holds. 


store = Gtk.ListStore(str, str, float) 


This creates a list store with three columns, two string columns, and a float column. 


Adding data to the model is done using[6tk .. ListStore.appena () jor 
Gtk.TreeStore.append () | depending upon which sort of model was created. 


For a[ctk.ListStore 


treeiter = store.append(["The Art of Computer Programming", 
"Donald E. Knuth", 25.46]) 


For al[6etk. TreeStorelyou must specify an existing row to append the new row to, using a 
Gtk.Treelter| or None for the top level of the tree: 
treeiter = store.append (None, ["The Art of Computer Programming", 

"Donald E. Knuth", 25.46]) 


Both methods return a[etk . TreeTterjinstance, which points to the location of the newly inserted row. 
You can retrieve a[Gtk . TreeIterlby calling[etk. TreeModel.get_iter () 


Once data has been inserted, you can retrieve or modify data using the tree iter and column index. 


print (store[treeiter][2]) + Prints value of third column 
store[treeiter] [2] = 42.15 


As with Pythonás built-in 1ist object you can use len () to get the number of rows and use slices to 
retrieve or set values. 


$ Print number of rows 

print (len (store)) 

$ Print all but first column 

print (store[treeiter] [1:]) 

$ Print last column 

print (store[treeiter] [-1]) 

$ Set last two columns 

store[treeiter][1:] = ["Donald Ervin Knuth", 41.99] 


Iterating over all rows of a tree model is very simple as well. 


for row in store: 
$ Print values of all columns 
print (row[:]) 


Keep in mind, that if you use[etk . TreeStorel the above code will only iterate over the rows of the top 
level, but not the children of the nodes. To iterate over all rows, uselGtk. TreeModel. foreach () 


def print_row(store, treepath, treeiter): 
print ("At" * (treepath.get_depth() 1), store[treeiter][:], sep="") 


store.foreach (print_row) 


Apart from accessing values stored in a[Gtk. TreeMode1|with the list-like method mentioned above, it 
1s also possible to either use[Gtk . Treelterjor[stk.TreePath]linstances. Both reference a particular 


row in a tree model. One can convert a path to an iterator by calling[Gtk . TreeModel.get_iter () 


As|Gtk. ListStorelcontains only one level, 1.e. nodes do not have any child nodes, a path is essentially 


the index of the row you want to access. 


$ Get path pointing to 6th row in list store 
path = Gtk.TreePath (5) 


treeiter = liststore.get_iter (path) 
$ Get value at 2nd column 
value = liststore.get_value(treeiter, 1) 


In the case of a path is a list of indexes or a string. The string form is a list of numbers 
separated by a colon. Each number refers to the offset at that level. Thus, the path 404 refers to the root 
node and the path 42:44 refers to the fifth child of the third node. 


+ Get path pointing to 5th child of 3rd row in tree store 
path = Gtk.TreePath([2, 4]) 

treeiter = treestore.get_iter (path) 

$ Get value at 2nd column 

value = treestore.get_value(treeiter, 1) 


Instances of|Gtk . TreePathican be accessed like lists, i.e. len (treepath) returns the depth of the 
item t reepath is pointing to, and treepath[1] returns the childás index on the ¡-th level. 


13.2. The View AI] 


While there are several different models to choose from, there is only one view widget to deal with. It 


works with either the list or the tree store. Setting up a[Gtk . TreeViewjis not a difficult matter. It needs 
a[etk. TreeModel|to know where to retrieve its data from, either by passing it to the[etk. TreeView 
constructor, or by calling|Gtk. TreeView.set_model () 


tree = Gtk.TreeView(model=store) 


Once the widget has a model, it will need to know how to display the model. It does this 
with columns and cell renderers.|hheaders_visiblelcontrols whether it displays column headers. 


Cell renderers are used to draw the data in the tree model in a specific way. There are a number of cell 
renderers that come with GTK+, for instance|ctk.CellRendererText 


Gtk.CellRendererPixbufland[ctk.CellRendererTogglel In addition, it is relatively easy to 
write a custom renderer yourself by subclassing a[etk .CellRenderer| and adding properties with 


GObject.Property () 


A|Gtk.TreeViewColunnjis the object that|stk. TreeViewJuses to organize the vertical columns in 


the tree view and hold one or more cell renderers. Each column may have a that will be visible if 


the[Gtk. TreeView|is showing column headers. The model is mapped to the column by using keyword 
arguments with properties of the renderer as the identifiers and indexes of the model columns as the 


arguments. 


renderer = Gtk.CellRendererPixbuf () 
column = Gtk.TreeViewColumn(cell_renderer=renderer, icon_name=3) 
tree. append_column (column) 


Positional arguments can be used for the column title and renderer. 


renderer = Gtk.CellRendererText () 
column = Gtk.TreeViewColumn ("Title", renderer, text=0, weight=1) 
tree.append_column (column) 


To render more than one model column in a view column, you need to create a[Gtk. TreeViewColunmn 
instance and use[Gtk. TreeViewColumn.pack_start () [to add the model columns to it. 


column = Gtk.TreeViewColumn ("Title and Author") 


title = Gtk.CellRendererText () 
author = Gtk.CellRendererText () 


column.pack_start (title, True) 
column.pack_start (author, True) 


column.add_attribute(title, "text", 0) 
column.add_attribute (author, "text", 1) 


tree.append_column (column) 


13.3. The Selectior A] 


Most applications will need to not only deal with displaying data, but also receiving input events from 
users. To do this, simply get a reference to a selection object and connect to the áchangedá signal. 


select = tree.get_selection() 
select.connect ("changed", on_tree_selection_changed) 


Then to retrieve data for the row selected: 


def on_tree_selection_changed(selection): 
model, treeiter = selection.get_selected() 
if treeiter is not None: 
print ("You selected", model[treeiter][0]) 


You can control what selections are allowed by calling[ctk .. TreeSelection.set_mode () 
Gtk.TreeSelection.get_selected ()|does not work if the selection mode is set to 
Gtk.SelectionMode.MULTIPLE|usejGtk. TreeSelection.get_selected_rows() 


instead. 


13.4. SortingA Y] 


Sorting is an important feature for tree views and is supported by the standard tree models 


(Gtk.TreeStorejand|[Gtk.ListStore), which implement the[etk. TreeSortablelinterface. 


13.4.1. Sorting by clicking on columnsAJ] 


A column of a[Gtk . TreeView|can easily made sortable with a call to 
Gtk.TreeViewColumn.set_sort_column_id()| Afterwards the column can be sorted by 
clicking on its header. 

First we need a simple|Gtk . TreeViewjand a[ctk . ListStorelas a model. 


model = Gtk.ListStore(str) 
model .append (["Benjamin"]) 


model .append(["Charles"]) 
model .append(["alfred"]) 
model .append(["Alfred"]) 


model .append(["charles"]) 
model .append(["david"]) 
model .append (["benjamin"]) 


( 
( 
( 
model .append(["David"]) 
( 
( 
( 


treeView = Gtk.TreeView(model=model) 


cellRenderer = Gtk.CellRendererText () 
column = Gtk.TreeViewColumn ("Title", renderer, text=0) 


The next step is to enable sorting. Note that the column_id (0 in the example) refers to the column of the 
model and not to the Tree Viewás column. 


column.set_sort_column_id(0) 


13.4.2. Setting a custom sort functiorlA Y] 


It is also possible to set a custom comparison function in order to change the sorting behaviour. As an 
example we will create a comparison function that sorts case-sensitive. In the example above the sorted 
list looked like: 


alfred 
Alfred 
benjamin 
Benjamin 
charles 
Charles 
david 
David 


The case-sensitive sorted list will look like: 


Alfred 
Benjamin 
Charles 
David 
alfred 
benjamin 
charles 
david 


First of all a comparison function is needed. This function gets two rows and has to return a negative 
integer if the first one should come before the second one, zero if they are equal and a positive integer if 
the second one should come before the first one. 


def compare (model, rowl, row2, user_data): 


sort_column, _ = model.get_sort_column_id() 
valuel = model.get_value(rowl, sort_column) 
value2 = model.get_value (row2, sort_column) 


if valuel < value2: 
return -1 

elif valuel == value2: 
return 0 

else: 
return 1 


Then the sort function has to be set by|Gtk . TreeSortable.set_sort_func() 


model.set_sort_func(0, compare, None) 


13.5. FilteringAY] 


Unlike sorting, filtering 1s not handled by the two models we previously saw, but by the 


(Guk TreemodelFi1terjelass. This clas, like[Gtk -TreeStorejand[Gtk Liststore isa 
It acts as a layer between the árealá model (a[etk. TreeStorelor a 

[Stk .ListStore), hiding some elements to the view. In practice, it supplies the[stk.. TreeView]with 
a subset of the underlying model. Instances of [stk . TreeMode1FilterJcan be stacked one onto 


another, to use multiple filters on the same model (in the same way youád use ¿ANDA clauses in a SQL 


request). They can also be chained with|[stk. TreeModelSort]jinstances. 
You can create a new instance of a[etk . TreeMode1Filterland give it a model to filter, but the 


easiest way 1s to spawn it directly from the filtered model, using the 
Gtk.TreeModel.filter_new() |method. 


filter = model.filter_new() 


In the same way the sorting function works, the[Gtk .. TreeMode1Filterjuses a ávisibilityá function, 


which, given a row from the underlying model, will return a boolean indicating if this row should be 


filtered out or not. Itás set by|[Gtk. TreeModelFilter.set_visible_func() 


filter.set_visible func(filter _func, data=None) 


The alternative to a ávisibilitya function is to use a boolean column in the model to specify which rows to 


filter. Choose which column with|Gtk. TreeModelFilter.set_visible_column() 


Letás look at a full example which uses the whole[Gtk . ListStorel-[6tk.TreeModelFilter]- 
Gtk.TreeModelFilter|-[Gtk.TreeView|stack. 


Treeview Filter Demo 


Software 
Firefox 
Eclipse 
Pitivi 
Netbeans 
Chrome 
Filezilla 
Bazaar 
Git 


Release Year 
2002 
2004 
2004 
1996 
2008 
2001 
2005 
2005 


Linux Kernel 1991 


GCC 
Frostwire 


Java 


1987 
2004 


Programming Language 
C++ 
Java 


Python 


Java 


import gi 


gi.require_version("Gtk", "3.0" 
from gi.repository import Gtk 


+ list of tuples for each software, 


software_list = [ 


class TreeViewFilterWindow(Gtk.Window) : 


("Firefox", 2002, " 

("Eclipse", 2004, " 
2004, "P 
", 1996, 
2008, "C 

"Filezilla", 2001, 


"Bazaar", 2005, "P 
it", 2005, "C"), 
inux Kernel", 19 
CC", 1987, "C"), 
"Frostwire", 2004 


def __init__ (self): 


CH), 
Java"), 
ython"), 
"Java"), 
HEM 
"o4+"), 


ython"), 
1 E 


"Java"), 


containing the software name, 


super ().__init__(title="Treeview Filter Demo" 


self.set_border, 


_width (10) 


initial release, 


+ Setting up the self.grid in which the elements are to be positioned 


self.grid = Gtk 


«Grid() 


self.grid.set_column_homogeneous (True) 
self .grid.set_row_homogeneous (True 


self.add (self.g 


4 Creating the ListStore model 
iststore = Gtk.ListStore(str, 
for software_ref in software_list: 

self .software_liststore.append (list (software_ref£)) 
None 


self.software_1l 


self.current_fi 


4 Creating the 
self.language_f 


+ setting the filter function, 


rid) 


lter_language 


filter, feeding it with the liststore model 


int, 


ilter = self.software_liststore.filter_new( 


note that we're not using the 


self.language_filter.set_visible_func(self.language_filter_func 


+ creating the treeview, making it use the filter as a model 
Gtk.TreeView(model=self.language_filter 
for i, column_title in enumerate ( 

["Software", 


self.treeview = 


renderer = 


+ creating buttons to filter by programming language, 


self.buttons = 
for prog_langual 


"Release Year", 


Gtk.CellRendererText () 
column = Gtk.TreeViewColumn (column_title, 
self .treeview.append_column (column) 


list () 
ge in ["Java", 


"c++, 


"Programming Language"] 


button = Gtk.Button (label=prog_language) 


self .buttons.append (button) 
self.on_selection_button_clicked) 


button.conn 


4 setting up th 
self.scrollable 


ect ("clicked", 


e layout, putting the treeview in a scrollwindow, 
_treelist = Gtk.ScrolledWindow ( 


self.scrollable_treelist.set_vexpand (True) 
self.grid.attach(self.scrollable_treelist, 0, 


self.grid.attac. 
self .button 
) 


h_next_to ( 


s[0], self.scrollable_treelist, 


for i, button in enumerate (self .buttons[1:]): 


self.grid.attach_next_to( 
self.buttons [i], 


button, 
) 


Gtk.PositionType.RIGHT, 


self.scrollable_treelist.add(self.treeview) 


self.show_al1 () 


def language_filter_func(self, model 


iter, 


data): 


"python", 


text=i) 


"None"]: 


Gtk.PositionType.BOTTOM, 1, 


1/1 


"""Tests if the language in the row is the one in the filter""" 


if ( 


self.current_filter_language is None 


or self.current_filter_language == "None" 


return True 
else: 
return mode 


def on_selection_button_clicked (self 
"""Called on any of the button clicks""" 
+ we set the current language filter to the button's label 
widget .get_label () 
self.current_filter_language) 
filter, which updates in turn the view 
self.language_filter.refilter () 


self.current_fi 


print ("%s language selected!" 


+ we update the 


= TreeViewFilterWin: 
.connect ("destroy", 
.show_al1 () 

.Mmain () 


l[iter][2] == self.current_filter_language 


lter_language 


dow () 
Gtk.main_quit) 


widget): 


and main programming languages used 


and adding the columns 


and setting up their events 


and the buttons in a row 
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14. CellRenderersA Y] 


Gtk.CellRenderer|widgets are used to display information within widgets such as the 
Gtk.TreeViewjor[stk.ComboBox| They work closely with the associated widgets and are very 


powerful, with lots of configuration options for displaying a large amount of data in different ways. There 


are seven|Gtk.CellRenderer|widgets which can be used for different purposes: 


Gtk.CellRendererText 


Gtk.CellRendererToggle 
O [Gtk.CellRendererPixbuf 
e [Gtk.CellRendererCombo 


O [Gtk.CellRendererProgress 
O [(Gtk.CellRendererSpinner 


e [Gtk.CellRendererSpin 


O [Gtk.CellRendererAccel 


14.1. CellRendererTex(ÁJ] 
A[Gtk.CellRendererText]renders a given text in its cell, using the font, color and style information 


provided by its properties. The text will be ellipsized if it is too long and the áellipsizeá property allows it. 


By default, text in[Gtk.CellRendererText|widgets is not editable. This can be changed by setting 


the value of the áeditableá property to True: 


cell.set_property ("editable", True) 


You can then connect to the áeditedá signal and update your[Gtk . TreeMode 1lJaccordingly. 


14.1.1. ExampldA] 


CellRendererText Example X 


r - . 
Editable Tex 


Fedora htp//fedoraproject.org/ 
Slackware http://www.slackware.com/ 
Sidux http//sidux.com/ 


import gi 


gi.require_version("Gtk", "3.0") 
from gi.repository import Gtk 


class CellRendererTextWindow(Gtk.Window) : 
def __init__ (self): 
super ().__init__(title="CellRendererText Example") 


self.set_default_size(200, 200) 


self.liststore = Gtk.ListStore(str, str) 
self.liststore.append(["Fedora", "https://fedoraproject.org/"]) 
self.liststore.append(["Slackware", "http://www.slackware.com/"]) 
self.liststore.append(["Sidux", "http://sidux.com/"]) 


0 J0 Us Y NROwOo0O Jocs gNnN Aa 


treeview = Gtk.TreeView(model=self.liststore) 


19 

20 renderer_text = Gtk.CellRendererText () 

21 column_text = Gtk.TreeViewColumn ("Text", renderer_text, text=0) 
22 treeview.append_column (column_text) 

23 

24 renderer_editabletext = Gtk.CellRendererText () 

25 renderer_editabletext.set_property ("editable", True) 
26 

Zl column_editabletext = Gtk.TreeViewColumn ( 

28 "Editable Text", renderer_editabletext, text=1 
29 ) 

30 treeview.append_column (column_editabletext) 

31 

32 renderer_editabletext.connect ("edited", self.text_edited) 
33 

34 self.add (treeview) 

35 

36 def text_edited(self, widget, path, text): 

37 self.liststore[path] [1] = text 

38 

39 

40 win = CellRendererTextWindow () 

41 win.connect ("destroy", Gtk.main_quit) 

42 win.show_all () 

43 Gtk.main () 


14.2. CellRendererToggleAJ] 
[stk .Cel1RendererTogg]1 elrenders a toggle button in a cell. The button is drawn as a radio- or 


checkbutton, depending on the áradioá property. When activated, 1t emits the átoggledá signal. 


As ajGtk.CellRendererTogglelcan have two states, active and not active, you most likely want to 


bind the áactiveá property on the cell renderer to a boolean value in the model, thus causing the check 
button to reflect the state of the model. 


14.2.1. ExampldAY] 


CellRendererToggle Exa... X 
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import gi 


gi.require_version("Gtk", "3.0") 
from gi.repository import Gtk 


class CellRendererToggleWindow (Gtk.Window) : 


win 


win. 
win. 


Gtk 


def __init__ (self): 
super ().__init_ _(title="CellRendererToggle Example") 


self.set_default_size(200, 200) 

self.liststore = Gtk.ListStore(str, bool, bool) 
self.liststore.append(["Debian", False, Truel) 
self.liststore.append(["OpenSuse", True, False]) 


self.liststore.append(["Fedora", False, False]) 


treeview = Gtk.TreeView(model=self.liststore) 


renderer_text = Gtk.CellRendererText () 


column_text = Gtk.TreeViewColumn("Text", renderer_text, text=0) 


treeview.append_column (column_text) 


renderer_toggle = Gtk.CellRendererToggle () 
renderer_toggle.connect ("toggled", self.on_cell_toggled) 


column_toggle = Gtk.TreeViewColumn ("Toggle", renderer_toggle, 


treeview.append_column (column_toggle) 


renderer_radio = Gtk.CellRendererToggle () 
renderer_radio.set_radio (True) 


renderer_radio.connect ("toggled", self.on_cell_radio_toggled) 


column_radio = Gtk.TreeViewColumn ("Radio", renderer_radio, 
treeview.append_column (column_radio) 


self.add (treeview) 


def on_cell_toggled(self, widget, path): 
self.liststore[path] [1] = not self.liststore[path] [1] 


def on_cell_radio_toggled(self, widget, path): 
selected_path = Gtk.TreePath (path) 
for row in self.liststore: 
row[2] = row.path == selected_path 


= CellRendererToggleWindow () 
connect ("destroy", Gtk.main_quit) 
show_all () 


.main () 


active=2) 


active=1) 


14.3. CellRendererPixbufÁAY] 


A|Gtk.CellRendererPixbuflican be used to render an image in a cell. It allows to render either a 
given Gdk.Pixbuf (set via the ápixbufá property) or a named icon (set via the áicon-nameá property). 


14.3.1. ExampldAJ] 


CellRendererPixbuf Exa... X 


import gi 


gi.require_version("Gtk", "3.0") 
from gi.repository import Gtk 


class CellRendererPixbufWindow(Gtk.Window) : 
def __init_ (self): 
super ().__init__(title="CellRendererPixbuf Example") 


po 


self.set_default_size(200, 200) 


po 


self.liststore = Gtk.ListStore(str, str) 
self.liststore.append(["New", "document-new"]) 
self.liststore.append(["Open", "document-open"]) 
self.liststore.append(["Save", "document-save"]) 


po 


mn 
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treeview = Gtk.TreeView(model=self.liststore) 


19 

20 renderer_text = Gtk.CellRendererText () 

2x column_text = Gtk.TreeViewColumn ("Text", renderer_text, text=0) 
22 treeview.append_column (column_text) 

23 

24 renderer_pixbuf = Gtk.CellRendererPixbuf () 

25 

26 column_pixbuf = Gtk.TreeViewColumn ("Image", renderer_pixbuf, icon_name=1) 
27 treeview.append_column (column_pixbuf) 

28 

29 self.add (treeview) 

30 

31 

32 win = CellRendererPixbufWindow () 

33 win.connect ("destroy", Gtk.main_quit) 

34 win.show_all () 

35 Gtk.main () 


14.4. CellRendererCombdAY[ 
[stk .Cel 1RendererCombolrenders text in a cell like a om in 1t is 
[Gt k . CellRendererCombo] 


derived. But while the latter offers a simple entry to edit the text,[ctk. Cel 1RendererComboJoffers a 
Gtk . ComboBox|widget to edit the text. The values to display in the combo box are taken from the 
Gtk.TreeModel|specified in the ámodelá property. 

The combo cell renderer takes care of adding a text cell renderer to the combo box and sets it to display 
the column specified by its átext-columná property. 


A|Gtk.CellRendererCombolcan operate in two modes. It can be used with and without an associated 
Gtk .Entry|widget, depending on the value of the áhas-entryá property. 


14.4.1. ExampleA] 


CellRendererCombo Exa... 


"ombi 


Television Samsung 
Mobile Phone LG 
DVD Player Sony 


import gi 
gi.require_version("Gtk", "3.0") 


from gi.repository import Gtk 


class CellRendererComboWindow (Gtk.Window) : 
def __init_ (self): 
super ().__init__(title="CellRendererCombo Example") 
self.set_default_size(200, 200) 


liststore_manufacturers = Gtk.ListStore(str) 


for item in manufacturers: 
liststore_manufacturers.append([item]) 


0 J0 014 0YNROwO0o0JAsOCOT,DSuynR 


self.liststore_hardware = Gtk.ListStore(str, str) 


manufacturers = ["Sony", "LG", "Panasonic", "Toshiba", 


19 self.liststore_hardware.append(["Television", "Samsung"]) 
20 self.liststore_hardware.append(["Mobile Phone", "LG"]) 
21 self.liststore_hardware.append(["DVD Player", "Sony"]) 
22 

23 treeview = Gtk.TreeView(model=self.liststore_hardware) 
24 

25 renderer_text = Gtk.CellRendererText () 

26 column_text = Gtk.TreeViewColumn ("Text", renderer_text, 
27 treeview.append_column (column_text) 

28 

29 renderer_combo = Gtk.CellRendererCombo () 


renderer_combo.set_property("editable", True) 


renderer_combo.set_property("text-column", 0) 
renderer_combo.set_property("has-entry", False) 


treeview.append_column (column_combo) 


self.add(treeview) 
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41 def on_combo_changed(self, widget, path, text): 
42 self.liststore_hardware[path] [1] = text 

43 

44 

45 win = CellRendererComboWindow () 

46 win.connect ("destroy", Gtk.main_quit) 

47 win.show_all () 

48 Gtk.main () 


14.5. CellRendererProgressA |] 


renderer_combo.set_property ("model", liststore_manufacturers) 


renderer_combo.connect ("edited", self.on_combo_changed) 


column_combo = Gtk.TreeViewColumn("Combo", renderer_combo, 


"Samsung" ] 


text=1) 


Gtk.CellRendererProgressjrenders a numeric value as a progress bar in a cell. Additionally, it 


can display a text on top of the progress bar. 


The percentage value of the progress bar can be modified by changing the ávalueá property. Similar to 


Gtk.ProgressBar| you can enable the activity mode by incrementing the ápulseá property instead of 


the ávalueá property. 


14.5.1. ExampldAJ] 


CellRendererProgress Exa... X 


Sabayon Es 
Zenwalk 0% 
SimplyMepis 0% 


0 300 0YNRAOwOoOJO0d,synNnR 


N N N th 
NRPOwo 


0 WNNNN»DNNDN» 
PRO0o0-JODdDmÉRDs 


GQ UU UU Y uy 
O) 014 WN 


0 0 uy 
vw 0 -—J 


Pp 
o 


Os ds ds ds ds ds ss 
000 -J5000suNnN Ra 


a 
pun 


daa a 
¡CSS 


o a 0a1a a a 
PRO0O_JO 


[o] 
N 


import gi 
gi.require_version("Gtk 


from gi.repository impo 


class CellRendererProgr 
def __init__ (self): 


e "3.0") 
rt Gtk, GLib 


essWindow (Gtk.Window) : 


super ().__init__(title="CellRendererProgress Example") 


self.set_defaul 


self.liststore 

self.current_it 
self.liststore. 
self.liststore. 


treeview = Gtk. 


renderer_text = 
column_text = G 
treeview.append 


renderer_progre 
column_progress 
"Progress", 


) 


t_size(200, 200) 


= Gtk.ListStore(str, int, bool) 


er = self.liststore.append(["Sabayon", 0, False]l) 


append(["Zenwalk", 0, False]l) 
append(["SimplyMepis", 0, False]) 


TreeView(model=self.liststore) 


Gtk.CellRendererText () 
tk. TreeViewColumn ("Text", renderer_text, text=0) 
| column (column_text) 


ss = Gtk.CellRendererProgress () 
= Gtk.TreeViewColumn ( 
renderer_progress, value=1, inverted=2 


treeview.append_column (column_progress) 


renderer_toggle 
renderer_toggle 
column_toggle = 


= Gtk.CellRendererToggle () 
.connect ("toggled", self.on_inverted_toggled) 
Gtk.TreeViewColumn ("Inverted", renderer_toggle, 


treeview.append_column (column_toggle) 


self.add (treevi 
self.timeout_id 


def on_inverted_tog 
self.liststorel 


def on_timeout (self 
new_value = sel 

if new_value > 
self.curren 
if self.cur 

self.re 
new_value = 


self.liststorel 
return True 


def reset_model (sel 

for row in self 
row[1] = O 
self.current_it 


win = CellRendererProgr 
win.connect ("destroy", 
win.show_all () 
Gtk.main () 


ew) 
= GLib.timeout_add(100, self.on_timeout, None) 


gled(self, widget, path): 
path] [2] = not self.liststorel[path] [2] 


, Uúser_data): 
f.liststore[self.current_iter][1] + 1 
100: 


t_iter = self.liststore.iter_next (self.current_iter) 


rent_iter is None: 

set_model () 
self.liststore[self.current_iter][1] + 1 
self.current_iter] [1] = new_value 

Les 

«liststore: 

er = self.liststore.get_iter_first() 


essWindow () 
Gtk.main_quit) 


14.6. CellRendererSpidA Y] 
[stk .Cel1RenderersSpin]renders text in a cell like o o it is 
[Gtk.CellRendererSpin] 


derived. But while the latter offers a simple entry to edit the text,|6tk.CellRendererSpinjoffers a 


Gtk. SpinButton|widget. Of course, that means that the text has to be parseable as a floating point 


number. 


The range of the spinbutton is taken from the adjustment property of the cell renderer, which can be set 
explicitly or mapped to a column in the tree model, like all properties of cell renders. 


[stk .Cel1RendererSpinjalso has properties for the climb rate and the number of digits to display. 
14.6.1. ExampldAJ] 


CellRendererSpin Exam... X 


Oranges 5 
Apples 4 


Bananas 2 


0 J0 Us Y NROwOo0O Jocs gNnN Aa 


N N tt 
RO 


NNNNNODNy 
JO 04 N 


O WU N N 
RO 0 


w 
59) 


S 45 0Y UU UY Y Y uy 
OMwW0 JO 0 


OT ds ds ds ds ds ds ds ds 
O0ow0-J0500+>uN A 


E 
O 
> 


import gi 


gi.require_version("Gtk", "3.0") 
from gi.repository import Gtk 


class CellRendererSpinWindow (Gtk.Window) : 


win 


win. 
win. 


Gtk 


def __init__ (self): 
super ().__init__(title="CellRendererSpin Example") 


self.set_default_size(200, 200) 


self.liststore = Gtk.ListStore(str, int) 
self.liststore.append(["Oranges", 5]) 
self.liststore.append(["Apples", 4]) 
self.liststore.append(["Bananas", 2]) 


treeview = Gtk.TreeView(model=self.liststore) 


renderer_text = Gtk.CellRendererText () 
column_text = Gtk.TreeViewColumn("Fruit", renderer_text, text=0) 
treeview.append_column (column_text) 


renderer_spin = Gtk.CellRendererSpin () 
renderer_spin.connect ("edited", self.on_amount_edited) 
renderer_spin.set_property ("editable", True) 


adjustment = Gtk.Adjustment ( 
value=0, 
lower=0, 
upper=100, 
step_increment=1, 
page_increment=10, 
page_size=0, 

) 


renderer_spin.set_property ("adjustment", adjustment) 


column_spin = Gtk.TreeViewColumn ("Amount", renderer_spin, text=1) 
treeview.append_column (column_spin) 


self.add (treeview) 
def on_amount_edited(self, widget, path, value): 


self.liststore[path] [1] = int (value) 


= CellRendererSpinWindow () 
connect ("destroy", Gtk.main_quit) 
show_all () 


.main() 
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15. ComboBoxAYl 


A|Gtk.ComboBox]Jallows for the selection of an item from a dropdown menu. They are preferable to 
having many radio buttons on screen as they take up less room. If appropriate, it can show extra 


information about each item, such as text, a picture, a checkbox, or a progress bar. 


Gtk .ComboBox]jis very similar to[etk. TreeView) as both use the model-view pattern; the list of valid 


choices is specified in the form of a tree model, and the display of the choices can be adapted to the data in 
the model by using[cell renderers] If the combo box contains a large number of items, it may be better to 
display them in a grid rather than a list. This can be done by calling 
Gtk.ComboBox.set_wrap_width () 


A default value can be set by calling with the index of the desired 


value. 


The widget usually restricts the user to the available choices, but it can optionally have 
an allowing the user to enter arbitrary text if none of the available choices are suitable. To 
do this, use one of the static methods or 

to create an instance. 


For a simple list of textual choices, the model-view API of[6tk . ComboBoxj|can be a bit overwhelming. 
In this case, [Gt k . ComboBoxTextJoffers a simple alternative. Both|[stk.. ComboBoxjand 


ComboBoxText|can contain an entry. 


15.1. ExampldAY] 


ComboBox Example 


import gi 


gi.require_version("Gtk", "3.0") 
from gi.repository import Gtk 


class ComboBoxWindow (Gtk. Window) : 
def _init__ (self): 
super ().__init__(title="ComboBox Example") 


self.set_border_width (10) 


name_store = Gtk.ListStore(int, str) 
name_store.append([1, "Billy Bob"]) 
name_store.append([11, "Billy Bob Junior"]) 
name_store.append([12, "Sue Bob"]) 
name_store.append([2, "Joey Jojo"]) 
name_store.append([3, "Rob McRoberts"]) 
name_store.append([31, "Xavier McRoberts"]) 


vbox = Gtk.Box(orientation=Gtk.Orientation.VERTICAL, spacing=6) 


name_combo = Gtk.ComboBox.new_with_model_and_entry (name_store) 


name_combo.connect ("changed", self.on_name_combo_changed) 
name_combo.set_entry_text_column (1 
vbox.pack_start (name_combo, False, False, 0) 


country_store = Gtk.ListStore (str) 
countries = [ 

"Austria", 

"Brazil", 

"Belgium", 

"France", 

"Germany", 

"Switzerland", 

"United Kingdom", 

"United States of America", 

"Uruguay", 


for country in countries: 
country_store.append ([country]) 


country_combo = Gtk.ComboBox.new_with_model (country_store) 


country_combo.connect ("changed", self.on_country_combo_changed) 


renderer_text = Gtk.CellRendererText () 
country_combo.pack_start (renderer_text, True) 
country_combo.add attribute (renderer_text, "text", 0) 
vbox.pack_start (country_combo, False, False, True) 


currencies = [ 
"Euro", 
"US Dollars", 
"British Pound”, 
"Japanese Yen", 
"Russian Ruble", 
"Mexican peso", 
"Swiss franc", 
] 
currency_combo = Gtk.ComboBoxText () 
currency_combo.set_entry_text_column (0) 


currency_combo.connect ("changed", self.on_currency_combo_changed) 


for currency in currencies: 
currency_combo.append_text (currency) 


currency_combo.set_active(0) 
vbox.pack_start (currency_combo, False, False, 0) 


self.add (vbox) 


def on_name_combo_changed(self, combo): 

tree_iter = combo.get_active_iter() 
if tree_iter is not None: 

model = combo.get_model () 

row_id, name = model[tree_iter][: 

print ("Selected: ID=%d, name=3s" % (row_id, name)) 
else: 

entry = combo.get_chila() 

print ("Entered: %s" % entry.get_text ()) 


N 


def on_country_combo_changed (self, combo) : 
tree_iter = combo.get_active_iter () 
if tree_iter is not None: 
model = combo.get_model () 
country = model [tree_iter] [0] 


print ("Selected: country=%s" % country) 


def on_currency_combo_changed (self, combo) : 
text = combo.get_active_text () 
if text is not None: 
print ("Selected: currency=%5" % text) 


win = ComboBoxWindow () 

win.connect ("destroy", Gtk.main_quit) 
win.show_all ( 

Gtk.main () 
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16. IconViewA Y] 


A|Gtk. IconViewlis a widget that displays a collection of icons in a grid view. It supports features such 
as drag and drop, multiple selections and item reordering. 


Similarly to[Gtk. TreeView|[Gtk.IconView|Juses a[Gtk . ListStorelfor its model. Instead of 
using Gtk . IconView|requires that one of the columns in its[Gtk . ListStorelcontains 


GdkPixbuf .Pixbuf objects. 


Gtk. IconView|supports numerous selection modes to allow for either selecting multiple icons at a 


time, restricting selections to just one item or disallowing selecting items completely. To specify a 


selection mode, the|Gtk. IconView.set_selection_mode ()|method is used with one of the 
Gtk.SelectionModelselection modes. 


16.1. ExampldÁY] 


iconview example.py  X 


import gi 


gi.require_version("Gtk", "3.0") 
from gi.repository import Gtk 
from gi.repository.GdkPixbuf import Pixbuf 


icons = ["edit-cut", "edit-paste", "edit-copy"] 


class IconViewWindow(Gtk.Window) : 
def __init__ (self): 
super ().__init__() 
self.set_default_size(200, 200) 


liststore = Gtk.ListStore(Pixbuf, str) 
iconview = Gtk.IconView.new() 
iconview.set_model (liststore) 
iconview.set_pixbuf_column (0) 


0 J3J0 Us WN ROO Jada gn Aa 


19 iconview.set_text_column (1) 

20 

21 for icon in icons: 

22 pixbuf = Gtk.IconTheme.get_default () .1load_icon(icon, 64, 0) 
23 liststore.append([pixbuf, "Label"]) 
24 

25 self.add(iconview) 

26 

27 

28 win = IconViewWindow () 

29 win.connect ("destroy", Gtk.main_quit) 

30 win.show_all() 

31 Gtk.main () 
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17. Multiline Text EditoriAJ] 


The[6tk . Text View]widget can be used to display and edit large amounts of formatted text. Like the 
1t has a model/view design. In this case the[Gtk . Text Buf £erlis the model which 
represents the text being edited. This allows two or more[Gt k . Text View|widgets to share the same 
and allows those text buffers to be displayed slightly differently. Or you could 


maintain several text buffers and choose to display each one at different times in the same 


Gtk.TextView|widget. 


17.1. The View/A] 


The[ctk . Text Viewlis the frontend with which the user can add, edit and delete textual data. They are 
commonly used to edit multiple lines of text. When creating a it contains its own default 
which you can access via the method. 

By default, text can be added, edited and removed from the[Gtk . Text Vi em] You can disable this by 
calling If the text is not editable, you usually want to hide the 
text cursor with as well. In some cases it may be useful 
to set the justification of the text with The text can be 
displayed at the left edge, (Gtk . Justification. LEFT), at the right edge 


(Gtk. Justification.RIGHT), centered (Gtk . Justification.CENTER] 
the complete width (Gtk.Justification.FILL). 


Another default setting of the|ctk. Text Vi ew|widget is long lines of text will continue horizontally until 
a break is entered. To wrap the text and prevent it going off the edges of the screen call 


Gtk.TextView.set_wrap_mode () 


17.2. The ModelAY] 


The|Gtk . TextBuf ferlis the core of the[Gtk . TextView|widget, and is used to hold whatever text 1s 
being displayed in the[etk . Text View] Setting and retrieving the contents is possible with 


and However, most text 
manipulation is accomplished with ¡terators, represented by a An iterator represents a 
position between two characters in the text buffer. Iterators are not valid indefinitely; whenever the buffer 
1s modified in a way that affects the contents of the buffer, all outstanding iterators become invalid. 


, Or distributed across 


Because of this, iterators canát be used to preserve positions across buffer modifications. To preserve a 
position, use A text buffer contains two built-in marks; an Ainsertá mark (which is the 
position of the cursor) and the áselection_boundá mark. Both of them can be retrieved using 

[Gtx .TextBuffer.get_insert () Jand 
respectively. By default, the location of a is not shown. This can be changed by calling 


Gtk.TextMark.set_visible() 


Many methods exist to retrieve a[Gtk . Text Iter| For instance, 


Gtk.TextBuffer.get_start_iter () |returns an iterator pointing to the first position in the text 


buffer, whereas[Gtk. TextBuffer.get_end_iter () [returns an iterator pointing past the last valid 


character. Retrieving the bounds of the selected text can be achieved by calling 
Gtk.TextBuffer.get_selection_bounds () 


To insert text at a specific position use[Gtk.TextBuffer.insert ()| Another useful method is 
Gtk.TextBuffer.insert_at_cursor () [which inserts text wherever the cursor may be currently 


positioned. To remove portions of the text buffer use[etk. TextBuffer.delete () 


In addition, can be used to locate textual matches in the buffer using 
Gtk.TextlIter.forward_search () |and[Gtk.TextIter.backward_search ()| The start 
and end iters are used as the starting point of the search and move forwards/backwards depending on 
requirements. 


173, TagsAY] 


Text in a buffer can be marked with tags. A tag is an attribute that can be applied to some range of text. 
For example, a tag might be called áboldá and make the text inside the tag bold. However, the tag concept 
1s more general than that; tags donát have to affect appearance. They can instead affect the behaviour of 
mouse and key presses, álocká a range of text so the user canát edit it, or countless other things. A tag is 


represented by a[Gtk . Text Tagjobject. One|[Gtk .. Text Tagjcan be applied to any number of text 


ranges in any number of buffers. 


Each tag is stored in ajetk.. TextTagTable] A tag table defines a set of tags that can be used together. 


Each buffer has one tag table associated with it; only tags from that tag table can be used with the buffer. 
A single tag table can be shared between multiple buffers, however. 


To specify that some text in the buffer should have specific formatting, you must define a tag to hold that 
formatting information, and then apply that tag to the region of text using 


Gtk.TextBuffer.create_tag()|land|Gtk.TextBuffer.apply_tag() 


tag = textbuffer.create_tag("orange_bg", background="orange") 
textbuffer.apply_tag(tag, start_iter, end_iter) 


The following are some of the common styles applied to text: 
e Background colour (Abackgroundá property) 
e Foreground colour (Aforegroundá property) 
e Underline (áunderlineá property) 
e Bold (weightá property) 


e Italics (ástyleá property) 


Strikethrough (ástrikethroughá property) 
e Justification (ájustificationá property) 
e Size (ásizeá and ásize-pointsá properties) 


e Text wrapping (awrap-modeá property) 


You can also delete particular tags later using or delete all tags in 
a given region by calling 
17.4. ExampldAY] 


TextView Example Xx 


aQa3a = q Qa 


his is some text inside of a GtkTextView. Select text and click one ofthe 


Y Editable Y Cursor Visible 


+.) No Wrapping Character Wrapping Word Wrapping 


gi. requize_version(MOtk, 13.0%) 


class SesrerDlslog (Gtk.Díalog) 


der _intt_(sel£, perent) 

Super). init (eitlen"search", Erensient_formparent, modal=Teue! 
seLs adi patrona ( 

Gek.STOCK_PIMD, 

tk Responsetype.0K, 

Ek. STOCK_CANCEL, 

tk ResponseType.CANCEL, 
, 


box = self.get_content_ares () 


label = GtX.Label(lobel=TInsert text you went Lo search for:") 
box .0dd(1abel) 


selt.omtey = Gek Entry 
A] 


PA 


clara Text Vicutlindow (St .Mándow) 


der init (010 
Gk Mindo, _inst_ (self, title="TextView Exemple") 


self_sot_default_size(=l, 350) 


selt-gria = Gek.Grid0 
eL ada tele. gria 


self.creste_texvierl 
self creste_toolbar) 
celo create buetons 1) 


def creste toolbar (se1£) 
koolbar = Gtk Toolbar (| 
self.grid.ettachítoolbar, 0, D, 3, 1) 


button_bold = Gtk.TociButtan 
button-bola.set_icon_neme (*£ormat-text-bo1d-aymbol ic") 
toolbar. insert (bueton_bold, 0) 


button ftalic = Gek.TootButton 
butronzitalic.set_icon nome ("format-text-Staltc-aysbolie") 
toolbaz. insert (button ftalle, 1) 


button_underláne = Gtk.ToolButton() 
butron_underline.set_£con_name ("£ormat-text-underline-symboLic") 
toolbaz insert (button_underline, 2) 


button_bold.comnect (Telicked", self .on button clicked, self.tag_bo1a) 
butron_1talic.comect ("elicked”, self.cn button clicked, self.tag_ttaltc) 
button underline.connect ("SL ickadn, self.onbutton_cLicked, s61£.tag_underline) 


toolbaz insert (Gtk SeparatortoolItem(), 3) 


sadio_justifylefe = Gtk RadioToolBatron () 
Falo Just Eylefe,set_icon_name ("£ormat-Justify-1est—eymboLic") 
hoolbar. insert (radio just fylest, 4) 


sadio_justifycenter = Gtk RadioTooIButton.mew_£rom_widget (radio_justs£yle£t) 
sadio_Justifycenter_set_Lcon_name ("£ormat justify -centes—symbol ic") 
hoolbar. insert (radio, Just ifycenter, 5) 


sadio_justiEyright = Gtk.RedioToolButton.new_fram_widget (radio_just1eyle£t) 
Esdio_ Just yright set_Scon,_ name (Mgormat Just se) -right simbolo") 
holas. insert (radio Just ifyeight, 5) 


sadio_justiyES11 = Gtk RadioToolButton,new_£rom_widget (radio_justifylese) 
Zadio_JustiEy£s11.aet_Lcon_namo ("£ormat justify Eo symnoLic") 
hoolbar. insert (radio just£fyEtal, 7) 


radio_Justi Eylest connect 1 
n Me po . 

radio_justi Eycenter.connect 1 

Ñ se po . 

radio_justieyright connect 

A se po . 

radio JustiEyEs11.connect 1 

4 se po . 


toolbar. insert (Gtk.SeparatosToolItem()y 8) 


button_clear = Gtk.ToolButton () 
button Clear,set_icon_name ("odit-clear-aymbolte") 
butron-Clear.connect ("elicked”, seL£.on_clear_clicked) 
toolbar. insert (bueton_cleaz, 9) 


toolbar. insert (Gtk.SeparatorToolItem(), 10) 


button_sesreh = Gtk.ToolButton 
button search. set_icon_name (Ysystem-seoreh-aymboltc%) 
button_searh.commect ("elicked”, sel£.cn search clicked) 
toolbaz Insert (butcon_search, 11) 


der creste_textview(se1£) 
serolLedwindow = Gtk.SerolLeditindow() 
scrolicduindou.aet_hexpand (True) 
scrolleduindow. set_vexpand (True 


self-grid.atrach(scrolleduindou, 0, 1, 3, 1) 


self-textvieu = ek TextVion() 
ef testuutfer > se1f testvien.get_bufer( 
SeLr textoueter.set_text 


, 


scrolleduindow.adó (101 E-textviem) 


self.tag_bold = self textbuffer.creste_tag("bold", uelght=Pango,HeSght BOLD) 
melfitag italic = self textbuttor.create_tag("itelicr, stylerdango.Seyle. ITALIC) 
SeLf.tag underline = self textbufter.creste-teq( 

> 


aelf.teg_found = self.testbuffer.create_tag("found", background="yellon") 


def creste buttons (se1) 
check_editable = Gtk CheckButton(label="Esitable") 
check editable.set_active (True) 
check_editable. connect ["Eoggled%, self.on_editable_toggled) 
self-gria.attach (check editable, 0, 2, ly 1) 


check_cursor » Gtk.CheckButton (Label="Cursor Visibie") 
Check_esrsor.set_active (True) 

check_editable.connect ["toggled", self.on_cursor_tosgled) 
self. gria.attach_next_tol 


» 


radio urapnone = Gtk.RadioWutton.now with Label_£rom_widget (None, "Io Kropping") 
SeLr.grid attachíradis_erapnone, O, 34 1, 1 


radio urapehar = Gtk_RedioButton.new_with_Label_£rom_ widget ( 
; Sl 
self.grid.ettach_mext_to( 

Zadio urapehar, radio_urapnone, Gtk.PositionType.RIGME, 1, 1 
, 


sadio_urapword = Gtk_RadicButton.now_with_Label_£ron_widgot ( 
=adio-urapnone, "Hora Wrsppingr 

> 

self.grid.ettach_mext_to( 
Tadio urapword, radio_urepchar, Gtk.PositionTa 


, 


sadio_urapnone_comnect ("toggled", sel£.cn_wrap_toggled, GtX.Mraplode_NONE) 
Zadio_urapehar connect ["oggled", sel£.cn-wrap-toggled, Gtk Mraplode. CHAR) 
Podio urapworá.comnect ["toggled”, sel£.on-wrap-toggled, GX Hraplode.HORO) 


der onbutton clicked(sel£, widget, tag) 
bounds = sel textbutter get selectión_bounás (| 

12 Lentbounda) = 0 
self textbuffer.apply_tagítag, start, end) 


der on_clesr_clicked(sel£, nidget) 
atan > sel textbueror get start_tter( 
end > selt.textburter.get_end_ttez() 
Self textiutfer.remove-slI tags(stert, end) 


def oneditable_toggled(sel£, widget) 
SeIT.textvien.set_editable (uidget .get_active()) 


der on_cursor_toggled(sel£, widget) 
Rolf textvien.set_cursor visible (widget .get_ective 0) 


der onurep_toggledísel£, widget, made) 
Ralf textview.set_wrspznode inode) 


der on_Justity toggledíself, widget, justificación) 
soli textvieu.ser_ Just fscation (justificacion) 


def on_sesreh clicked(sel£, widget) 
alstog = Sesrchialog(se1£) 
sespanas - dislog.cun 
ÍE response == Gtk.ResponseType.0K 
CurmocimarR = dez tentbueforget_imsert 
atar = self textbueres.got_lter_at_mark (cursor_mark) 
LE start_get_ offset () == self textbutter.get_chas_count () 
start > self textburtez.get_otare_icor 0 


sel£.scarch_end mork (dislog.entey.get_text (), start) 
distog.destroy Ur 


def sesrch_end mark (sel£, text, start) 
end > selt textburter.get_end_tter() 
maten = start. forvard_nearchltext, 0, end) 


self.textbuffer.apply_tag(self.tag_found, match_start, match_end) 
Solo search_and mark (text, matchená) 


- Textvicuiindon 
connect ("destroy", Gtk.main_quit) 
e] 

matri 
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18. DialogdA Y] 


Dialog windows are very similar to standard windows, and are used to provide or retrieve information 
from the user. They are often used to provide a preferences window, for example. The major difference a 
dialog has is some prepacked widgets which layout the dialog automatically. From there, we can simply 
add labels, buttons, check buttons, etc. Another big difference is the handling of responses to control how 
the application should behave after the dialog has been interacted with. 


There are several derived Dialog classes which you might find useful.[stk.MessageDialog]lis used 


for most simple notifications. But at other times you might need to derive your own dialog class to provide 
more complex functionality. 


18.1. Custom DialogsA] 


To pack widgets into a custom dialog, you should pack them into the available via 
Gtk.Dialog.get_content_area ()| To just add ajetk . Buttonjto the bottom of the dialog, you 
could use the|Gtk.Dialog.add_button ()|method. 


A ámodalá dialog (that is, one which freezes the rest of the application from user input), can be created by 
calling Gtk.Dialog.set_modal on the dialog or set the flags argument of the|etk.Dialog 


constructor to include the|6tk.DialogFlags.MODALjflag. 


Clicking a button will emit a signal called áresponseá. If you want to block waiting for a dialog to return 
before returning control flow to your code, you can call[6tk.Dialog. run () | This method returns an 
int which may be a value from the[Gtk . ResponseTypelor it could be the custom response value that 


you specified in the[6tk .Dialogjconstructor or[Gtk.Dialog.add_button () 
Finally, there are two ways to remove a dialog. The|Gtk . Widget .hide () [method removes the dialog 


from view, however keeps 1t stored in memory. This is useful to prevent having to construct the dialog 


again 1f 1t needs to be accessed at a later time. Alternatively, the[stk . Widget . destroy () [method can 


be used to delete the dialog from memory once it is no longer needed. It should be noted that if the dialog 
needs to be accessed after it has been destroyed, 1t will need to be constructed again otherwise the dialog 
window will be empty. 


18.1.1. ExampleAY] 


My Dialog 


This is a dialog to display additional information 


1 import gi 
2 
3 gi.require_version("Gtk", "3.0") 
4 from gi.repository import Gtk 
5 
6 
7 class DialogExample (Gtk.Dialog): 
8 def __init_ (self, parent): 
9 super().__init_ _(title="My Dialog", transient_for=parent, flags=0) 
LO self.add_buttons ( 
11 Gtk.STOCK_CANCEL, Gtk.ResponseType.CANCEL, Gtk.STOCK_OK, Gtk.ResponseType.OK 
12 ) 
13 
14 self.set_default_size(150, 100) 
15 
16 label = Gtk.Label (label="This is a dialog to display additional information") 
17 
18 box = self.get_content_area( ) 
19 box.add (label) 
20 self.show_all () 
21 
22 
23 class DialogWindow(Gtk.Window) : 
24 def __init__ (self): 
25 Gtk.Window.__init__ (self, title="Dialog Example") 
26 
201 self.set_border_width(6) 
28 
29 button = Gtk.Button (label="0pen dialog") 
30 button.connect ("clicked", self.on_button_clicked) 
31 
32 self.add (button) 
33 
34 def on_button_clicked(self, widget): 
35 dialog = DialogExample (self) 
36 response = dialog.run() 
37 
38 if response == Gtk.ResponseType.OK: 
39 print ("The OK button was clicked") 
40 elif response == Gtk.ResponseType.CANCEL: 
41 print ("The Cancel button was clicked") 
42 
43 dialog.destroy () 
44 
45 


46 win = DialogWindow () 

47 win.connect ("destroy", Gtk.main_quit) 
48 win.show_all () 

49 Gtk.main () 


18.2. MessageDialogA Y] 
[Stk .MessageDialoglis a convenience class, used to create simple, standard message dialogs, with a 


message, an icon, and buttons for user response. You can specify the type of message and the text in the 


Gtk.MessageDialogjconstructor, as well as specifying standard buttons. 


In some dialogs which require some further explanation of what has happened, a secondary text can be 
added. In this case, the primary message entered when creating the message dialog is made bigger and set 
to bold text. The secondary message can be set by calling 


18.2.1. ExampldAJ] 


This is an INFO MessageDialog 


And this is the secondary text that explains things. 


import gi 


gi.require_version("Gtk", "3.0") 
from gi.repository import Gtk 


class MessageDialogWindow(Gtk.Window) : 


win 
win 
win 
Gtk 


def 


def 


def 


def 


def 


—_init__ (self): 
super ().__init__(title="MessageDialog Example") 


box = Gtk.Box (spacing=6) 
self .add (box) 


buttonl = Gtk.Button (label="Information") 
buttonl.connect ("clicked", self.on_info_clicked) 
box.add (button1) 


button2 = Gtk.Button (label="Error") 
button2.connect ("clicked", self.on_error_clicked) 
box .add (button2) 


button3 = Gtk.Button (label="Warning") 
button3.connect ("clicked", self.on_warn_clicked) 
box .add (button3) 


button4 = Gtk.Button (label="Question") 
button4.connect ("clicked", self.on_question_clicked) 
box.add (button4) 


on_info_clicked(self, widget): 

dialog = Gtk.MessageDialog ( 
transient_for=self, 
flags=0, 
message_type=Gtk.MessageType. INFO, 
buttons=Gtk.ButtonsType.0K, 
text="This is an INFO MessageDialog", 

) 

dialog.format_secondary_text ( 
"And this is the secondary text that explains things." 

) 

dialog.run() 

print ("INFO dialog closed") 


dialog.destroy () 


on_error_clicked(self, widget): 

dialog = Gtk.MessageDialog ( 
transient_for=self, 
flags=0, 
message_type=Gtk.MessageType.ERROR, 
buttons=Gtk.ButtonsType.CANCEL, 
text="This is an ERROR MessageDialog", 

) 

dialog.format_secondary_text ( 
"And this is the secondary text that explains things." 

) 

dialog.run() 

print ("ERROR dialog closed") 


dialog.destroy () 


on_warn_clicked(self, widget): 
dialog = Gtk.MessageDialog ( 
transient_for=self, 
flags=0, 
message_type=Gtk.MessageType. WARNING, 
buttons=Gtk.ButtonsType.OK_CANCEL, 
text="This is an WARNING MessageDialog", 
) 
dialog.format_secondary_text ( 
"And this is the secondary text that explains things." 
) 
response = dialog.run() 
if response == Gtk.ResponseType.OK: 
print ("WARN dialog closed by clicking OK button") 
elif response == Gtk.ResponseType.CANCEL: 
print ("WARN dialog closed by clicking CANCEL button") 


dialog.destroy () 


on_question_clicked (self, widget): 
dialog = Gtk.MessageDialog ( 
transient_for=self, 
flags=0, 
message_type=Gtk.MessageType. QUESTION, 
buttons=Gtk.ButtonsType.YES_NO, 
text="This is an QUESTION MessageDialog", 
) 
dialog.format_secondary_text ( 
"And this is the secondary text that explains things." 
) 
response = dialog.run() 
if response Gtk.ResponseType.YES: 
print ("QUESTION dialog closed by clicking YES button") 
elif response == Gtk.ResponseType.NO: 
print ("QUESTION dialog closed by clicking NO button") 


dialog.destroy () 


= MessageDialogWindow () 


.connect ("destroy", Gtk.main_quit) 
.show_al1 () 
.main () 


18.3. FileChooserDialogA Y] 

The is suitable for use with áFile/Opená or áFile/Saveá menu items. You 
can use all of the methods on the file chooser dialog as well as those for 

When creating a[ctk .FileChooserDialog]you have to define the dialogás purpose: 


e To select a file for opening, as for a File/Open command, use 


Gtk.FileChooserAction.OPEN 


e Tosave a file for the first time, as for a File/Save command, use 


Gtk.FileChooserAction.SAVE| and suggest a name such as ¿Untitledá with 


Gtk.FileChooser.set_current_name () 


e Tosave a file under a different name, as for a File/Save As command, use 


Gtk.FileChooserAction.SAVEJ] and set the existing filename with 


Gtk.FileChooser.set_filename () 


e To choose a folder instead of a file, usel[Gtk.FileChooserAction.SELECT_FOLDER 
Gtk.FileChooserDialog 


inherits from|Gtk . Dialog]| so buttons have response IDs such as 


and which can be specified in the 
constructor. In contrast to you can not use custom 
response codes with It expects that at least one button will have of the 
following response IDs: 


e [Gtk.ResponseType . ACCEPT] 
e [Gtk.ResponseType .0X] 
e [ctk.ResponseType .YES 
e [stk.ResponseType . APPLY] 


When the user is finished selecting files, your program can get the selected names either as filenames 


(Gtk.FileChooser.get_filename ()| or as URlIs (Gtk.FileChooser.get_uri ()). 


By default, only allows a single file to be selected at a time. To enable multiple 
files to be selected, use Retrieving a list of 
selected files is possible with either or 


Gtk.FileChooserlalso supports a variety of options which make the files and folders more 


configurable and accessible. 


e [Gtk.FileChooser.set_local_only () | Only local files can be selected. 


e Gtk.FileChooser.show_hidden (): Hidden files and folders are displayed. 


Gtk.FileChooser.set_do_overwrite confirmation ()| If the file chooser was 


configured in[Gtk.FileChooserAction. SAVE|mode, 1t will present a confirmation dialog 
1f the user types a file name that already exists. 


Furthermore, you can specify which kind of files are displayed by creating [stk . FileFi1lterjobjects 
and calling[etk.FileChooser.add_filter ()| The user can then select one of the added filters 


from a combo box at the bottom of the file chooser. 


18.3.1. ExampleA] 


Cancel Please choose a file 


Recent 


4 | (Gsebp | Projekte | gnome | PyGObject-Tutorial | examples 


Home 


v 


Bilder =] builder_example.glade 790 bytes 12/31/13 
¡| builder_example.py 359 bytes 12/31/13 
Dokumente button_example.py 1.1kB 13:51 
cellrendereraccel example.py 1.5 kB 12/31/13 
cellrenderercombo_example.py 1.6kB 12/31/13 
Musik cellrendererpixbuf example.py 957 bytes 12/31/13 
-] cellrendererprogress example.py 2.0 kB 12/31/13 
cellrendererspin_example.py 1.2 kB 12/31/13 
cellrenderertext_example.py 1.2 kB 12/31/13 
| cellrenderertoggle example.py 1.6 kB 12/31/13 
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import gi 


gi.require_version("Gtk", "3.0") 
from gi.repository import Gtk 


class FileChooserWindow(Gtk.Window) : 


win 
win 
win 
Gtk 


def __init__ (self): 
super ().__init__(title="FileChooser Example") 


box = Gtk.Box (spacing=6) 
self .add (box) 


buttonl = Gtk.Button (label="Choose File") 
buttonl.connect ("clicked", self.on_file_clicked) 
box.add (button1) 


button2 = Gtk.Button (label="Choose Folder" 
button2.connect ("clicked", self.on_folder_clicked) 
box.add (button2) 


def on_file_clicked(self, widget): 
dialog = Gtk.FileChooserDialog( 
title="Please choose a file", parent=self, action=Gtk.FileChooserAction.OPEN 
) 
dialog.add_buttons ( 
Gtk.STOCK_CANCEL, 
Gtk.ResponseType.CANCEL, 
Gtk.STOCK_OPEN, 
Gtk.ResponseType.OK, 


self.add_filters (dialog) 


response = dialog.run() 
if response == Gtk.ResponseType.OK: 

print ("Open clicked") 

print ("File selected: " + dialog.get_filename ()) 
elif response == Gtk.ResponseType.CANCEL: 

print ("Cancel clicked") 


dialog.destroy ( 


def add_filters(self, dialog): 
filter_text = Gtk.FileFilter () 
filter_text.set_name("Text files") 
filter_text.add_mime_type ("text/plain") 
dialog.add_filter(filter_text) 


filter_py = Gtk.FileFilter () 
filter_py.set_name ("Python files") 
filter_py.add_mime_type("text/x-python") 
dialog.add_filter(filter_py) 


filter_any = Gtk.FileFilter () 
filter_any.set_name ("Any files") 
filter_any.add_pattern("*") 
dialog.add_filter(filter_any) 


def on_folder_clicked(self, widget): 
dialog = Gtk.FileChooserDialog( 
title="Please choose a folder", 
parent=self, 
action=Gtk.FileChooserAction.SELECT_FOLDER, 
) 
dialog.add_buttons ( 
Gtk.STOCK_CANCEL, Gtk.ResponseType.CANCEL, "Select", Gtk.ResponseType.OK 
) 
dialog.set_default_size(800, 400) 


response = dialog.run() 
if response == Gtk.ResponseType.OK: 

print ("Select clicked") 

print ("Folder selected: " + dialog.get_filename ()) 
elif response == Gtk.ResponseType.CANCEL: 

print ("Cancel clicked") 


dialog.destroy ( 


= FileChooserWindow () 

.connect ("destroy", Gtk.main_quit) 
.show_all () 

.main () 
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19. PopoversÁY] 


The|Gtk . Popoverlis a separate window used for displaying additional information and is often used 
with button menus and context menus. Popovers are visually connected to a related widget with a small 


triangle. Their uses are similar to those of dialog windows with the advantage of being less disruptive and 
having a connection with the widget the popover is pointing to. 


A Popover can be created with|[Gtk . Popover| for opening the popover use|Gtk . Popover .popup () 


19.1. Custom PopoverAJ] 
A widget can be added to a popover using[stk. Container. add ()] 


19.1.1. ExampldAJ] 


Popover Demo x 


Click Me 


Item 1 


Item 2 


import gi 


gi.require_version("Gtk", "3.0") 
from gi.repository import Gtk 


class PopoverWindow(Gtk.Window) : 
def __init__ (self): 
super ().__init_ _(title="Popover Demo") 
self.set_border_width (10) 
self.set_default_size(300, 200) 


outerbox = Gtk.Box(spacing=6, orientation=Gtk.Orientation.VERTICAL) 
self.add (outerbox) 


self .popover = Gtk.Popover () 
vbox = Gtk.Box(orientation=Gtk.Orientation.VERTICAL) 
vbox.pack_start (Gtk.ModelButton (label="Item 1"), False, True, 10) 
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19 vbox.pack_start (Gtk.Label (label="Item 2"), False, True, 10) 
20 vbox.show_all () 

21 self .popover.add (vbox) 

22 self .popover.set_position(Gtk.PositionType.BOTTOM) 

23 

24 button = Gtk.MenuButton (label="Click Me", popover=self.popover) 
2D outerbox.pack_start (button, False, True, 0) 

26 

27 

28 win = PopoverWindow () 

29 win.connect ("destroy", Gtk.main_quit) 

30 win.show_all() 

31 Gtk.main () 


19.2. Menu PopoverA Y] 


A popover can be created from a[Gio.MenuModel] Jusing[6tk.Popover .new_from_model () land 
can be changed after creation with[6tk. Popover .bind_model () 


Passing a[Gio . MenuMode las almenu_mode1]largument to the[stk . MenuBut t on|constructor 


implicitly creates a popover. 


19.2.1. ExampldAJ] 


Main Window = |] Xx 


import sys 
import gi 


gi.require_version("Gtk", "3.0") 
from gi.repository import Gio, Gtk 


+ This would typically be its own file 


MENU_XML = """ 
<?xml version="1.0" encoding="UTF-8"7?> 
<interface> 
<menu id="app-menu"> 
<section> 
<item> 
<attribute name="label">About</attribute> 
<attribute name="action">app.about</attribute> 
</item> 
<item> 
<attribute name="label">Quit</attribute> 
<attribute name="action">app.quit</attribute> 
</item> 
</section> 
</menu> 
</interface> 


class AppWindow (Gtk.ApplicationWindow) : 
def __init__ (self, *args, **kwargs): 
super ().__init__(*args, **kwargs) 

self.set_default_size(300, 200) 


outerbox = Gtk.Box(spacing=6, orientation=Gtk.Orientation.VERTICAL) 
self.add (outerbox) 
outerbox.show () 


builder = Gtk.Builder.new_from_string(MENU_XML, -1) 
menu = builder.get_objJect ("app-menu") 


button = Gtk.MenuButton (menu_model=menu) 


outerbox.pack_start (button, False, True, 0) 
button.show () 
self.set_border _width(50) 


class Application (Gtk.Application): 


if 


def __init__ (self, *args, **kwargs): 
super ().__init__(*args, application_id="org.example.myapp", **kwargs) 
self.window = None 
def do_startup (self): 
Gtk.Application.do_startup (self) 
action = Gio.SimpleAction (name="about") 
action.connect ("activate", self.on_about) 
self.add_action (action) 
action = Gio.SimpleAction (name="quit") 
action.connect ("activate", self.on_quit) 
self.add_action (action) 
def do_activate(self): 
+ We only allow a single window and raise any existing ones 
if not self.window: 
+ Windows are associated with the application 
+ when the last one is closed the application shuts down 
self.window = AppWindow(application=self, title="Main Window") 
self.window.present () 
def on_about (self, action, param): 
about_dialog = Gtk.AboutDialog(transient_for=self.window, modal=True) 
about_dialog.present () 
def on_quit (self, action, param): 
self.quit () 
name == "_ main": 
app = Application () 


app 


.run(sys.argv) 


19.3. See AlsdAY] 


Next/Previous] 


O Copyright GNU Free Documentation License 1.3 Revision £d9dd7a4. 


Built with [SphinxJusing a[theme|provided by|Read the Docs 


Read the Docs v: latest 


Versions 
latest 


Downloads 


On Read the Docs 


Free document hosting provided by|Read the Docs 


Python GTK+ 3 Tutorial 


latest 


| 


. Installation 
. Getting Started 


. How to Deal With Strings 
. Widget Galler 

. Layout Containers 

. Label 

. Entr 

. Button Widgets 

0. Expander 

1. ProgressBar 

2. Spinner 

3. Tree and List Widgets 
4. CellRenderers 

5. ComboBox 

6. IconView 

7. Multiline Text Editor 
8. Dialogs 

9. Popovers 

0. Clipboar 

o 

1. Drag and Drop 

2. Glade and Gtk.Builder 
3. Objects 

4. Application 


aa =Te]e]= 
ua) 
[o] 
Un 
2, 
el 
Un 


— 


[om 


, 


0.0 0.0.0 
O) 


OU 
e] 
yal 
el 
o 
O 
[ab] 
-- 
o 
Aa 


Es 
O 
[] 
[=] 
2) 


Python GTK+ 3 Tutorial 


Docs|» 
0. 
dit on GitHub 


e... 
548 
Q 
E 
o 
S 
A 
a 


20. Clipboard 
[stk .C1ipboa ralprovides a storage area for a variety of data, including text and images. Using a 


clipboard allows this data to be shared between applications through actions such as copying, cutting, and 
pasting. These actions are usually done in three ways: using keyboard shortcuts, using a 


Gtk.Menultemj and connecting the functions to[6tk . But ton|widgets. 


There are multiple clipboard selections for different purposes. In most circumstances, the selection named 
CLIPBOARD is used for everyday copying and pasting. PRIMARY is another common selection which 
stores text selected by the user with the cursor. 


20.1. ExampldÁY] 


Clipboard Example x 


Copy Text Paste Text 


Copy Image Paste Image 


0 3004 YNROwD0DOoO-JOoOCdS NR 


Ko) 


import gi 


gi.require_version("Gtk", "3.0") 
from gi.repository import Gtk, Gdk 


class ClipboardWindow(Gtk.Window) : 
def __ init_ (self): 
super ().__init_ (title="Clipboard Example") 


grid = Gtk.Griad() 


self.clipboard = Gtk.Clipboard.get (Gdk. SELECTION_CLIPBOARD) 
self.entry = Gtk.Entry() 
self.image = Gtk.Image.new_from_icon_name ("process-stop", Gtk.IconSize.MENU) 


button_copy_text = Gtk.Button (label="Copy Text") 
button_paste_text = Gtk.Button(label="Paste Text") 
button_copy_image = Gtk.Button(label="Copy Image") 
button_paste_image = Gtk.Button (label="Paste Image") 
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grid.add (self.entry) 
grid.attach(self.image, 0, 1, 


1 
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grid.attach(button_copy_text, 1, 0, 1, 1) 
grid.attach(button_paste_text, 2, 0, 1, 1) 
grid.attach(button_copy_image, 1, 1, 1, 1) 
grid.attach(button_paste_image, 2, 1, 1, 1) 


button_copy_text.connect ("clicked", self.copy_text) 
button_paste_text.connect ("clicked", self.paste_text) 
button_copy_image.connect ("clicked", self.copy_image) 
button_paste_image.connect ("clicked", self.paste_image) 


self.add (grid) 


def copy_text (self, widget): 
self.clipboard.set_text (self.entry.get_text(), -1) 


def paste_text (self, widget): 
text = self.clipboard.wait_for_text () 
if text is not None: 
self.entry.set_text (text) 
else: 
print ("No text on the clipboard.") 


def copy_image (self, widget): 
if self.image.get_storage_type() == Gtk.ImageType.PIXBUF: 
self.clipboard.set_image(self.image.get_pixbuf ()) 
else: 
print ("No image has been pasted yet.") 


def paste_image (self, widget): 
image = self.clipboard.wait_for_image() 
if image is not None: 
self.image.set_from_pixbuf (image) 


win = ClipboardWindow () 

win.connect ("destroy", Gtk.main_quit) 
win.show_all () 

Gtk.main () 


Next|Previous 


O Copyright GNU Free Documentation License 1.3 Revision £d9dd7a4. 


Built with using a[theme]provided by [Read the Docs 


Read the Docs v: latest 


Versions 
lates 


aa 


Free document hosting provided by|Read the Docs 


Python GTK+ 3 Tutorial 


latest 


| 


. Installation 
. Getting Started 


. How to Deal With Strings 
. Widget Galler 
. Layout Containers 


. Button Widgets 
0. Expander 
1. ProgressBar 
2. Spinner 
3. Tree and List Widgets 
4. CellRenderers 
5. ComboBox 
6. IconView 
7. Multiline Text Editor 
8. Dialogs 
9. Popovers 
0. Clipboar 
1. Drag and Drop 
1.1. Target Entries 
21.2. Drag Source Signals 


21.3. Drag Destination Signals 


21.4. Example 
. Glade and Gtk.Builder 


0000000000O00O00Oo00Oo0Oo0Oo0Oo0Oo0Oo00Oo00Oo900AOO 
Niel Ip—]p—]Pp—=IP—IP—i—]l—Iipoloo lola lala lolo 
Sl E 
als 2. 
o, o 
9%) 
a 


O0O00O00oO 


s 
SIS 
ao 


o... 

NO) 

E 
O 
o 
O 
O 
er 
102) 


. Application 


OU 
e] 
yal 
el 
o 
O 
[ab] 
-- 
o 
Aa 


.. 
5 
O 
[an] 
[en] 
(e2) 


Python GTK+ 3 Tutorial 


E 
o 
O 
Dn 
y 


l. 
dit on GitHub 


0... 
E] e 
U 
= 
[ao] 
Ue 
[ab] 
=] 
a 
U 
5] 
o 
"a 


21. Drag and DroplA Y] 


Note 


Versions of PyGObject < 3.0.3 contain a bug which does not allow drag and drop to function correctly. 
Therefore a version of PyGObject >= 3.0.3 is required for the following examples to work. 


Setting up drag and drop between widgets consists of selecting a drag source (the widget which the user 
starts the drag from) with the[etk .Widget.drag_source_set () [method, selecting a drag 


destination (the widget which the user drops onto) with the|Gtk . Widget .drag_dest_set () [method 
and then handling the relevant signals on both widgets. 


Instead of using|[Gtk . Widget .drag_source_set () land[Gtk. Widget .drag_dest_set () 


some specialised widgets require the use of specific functions (such as[Gtk. TreeViewJand 


Gtk.IconView). 


A basic drag and drop only requires the source to connect to the Adrag-data-getá signal and the destination 
to connect to the ádrag-data-receivedá signal. More complex things such as specific drop areas and custom 


drag icons will require you to connect toladditional signalsjand interact with the Gdak .DragContext 
object it supplies. 


In order to transfer data between the source and destination, you must interact with the 


Gtk.SelectionDatalvariable supplied in the|[ádrag-data-getáland [áadrag-data-receivedá|signals using 
the[etk . Select ionDat a] 


Gtk.SelectionDatajget and set methods. 


21.1. Target EntriesAY] 


To allow the drag source and destination to know what data they are receiving and sending, a common list 


of[Gtk.TargetEntry?' sjare required. A[Gtk.TargetEnt ryldescribes a piece of data that will be 


sent by the drag source and received by the drag destination. 


There are two ways of adding|Gtk.TargetEntry” sito a source and destination. If the drag and drop is 
simple and each target entry is of a different type, you can use the group of methods 


If you require more than one type of data or wish to do more complex things with the data, you will need 


to create the[Gtk . TargetEntry' s]using the method. 
21.2. Drag Source SignalgA Y] 


Name When it is emitted 
drag-begin User starts a drag 
drag-data-get When drag data is requested by the destination 


When a drag with the action 


apa ande Gdk.DragAction.MOVE is completed 


drag-end When the drag is complete 


21.3. Drag Destination SignalgÁ Y] 


Common Purpose 
Set-up drag icon 


Transfer drag data from source 
to destination 


Delete data from the source to 
complete the ámoveá 


Undo anything done in 
drag-begin 


Name When it is emitted Common Purpose 
; . Allow only certain areas to be 

drag-motion Drag icon moves over a drop area 
dropped onto 

drag-drop Icon is dropped onto a drag area ANO Ii OS 
dropped onto 

, When drag data is received by the Transfer drag data from source to 
drag-data-recelved e AE 
destination destination 


21.4. ExampldÁY] 


Drag and Drop Demo 


Drop something on mel! 


Item 3 


e) Images 


import gi 


gi.require_version("Gtk", "3.0") 
from gi.repository import Gtk, Gdk, GdkPixbuf 


(TARGET_ENTRY_TEXT, TARGET_ENTRY_PIXBUF) = range (2) 
(COLUMN_TEXT, COLUMN_PIXBUF) = range (2) 


DRAG_ACTION = Gdk.DragAction.COPY 


class DragDropWindow(Gtk.Window) : 
def _init__ (self): 


super ().__init__(title="Drag and Drop Demo") 


vbox = Gtk.Box (orientation=Gtk.Orientation.VERTICAL, spacing=6) 
self .add (vbox) 


hbox = Gtk.Box (spacing=12) 
vbox.pack_start (hbox, True, True, 0) 


self.iconview = DragSourcelconView() 


self.drop_area = DropArea() 


hbox.pack_start (self .iconview, True, True, 0) 
hbox.pack_start (self .drop_area, True, True, 0) 


button_box = Gtk.Box (spacing=6) 
vbox.pack_start (button_box, True, False, 0) 


image_button = Gtk.RadioButton.new_with_label_from_widget (None, "Images") 
image_button.connect ("toggled", self.add_image_targets) 
button_box.pack_start (image_button, True, False, 0) 


text_button = Gtk.RadioButton.new_with_label_from_widget (image_button, "Text") 
text_button.connect ("toggled", self.add_text_targets) 


button_box.pack_start (text_button, True, False, 0) 


self.add_image_targets () 


def add_image_targets(self, button=None): 


targets = Gtk.TargetList.new(([]) 
targets.add_image_targets(TARGET_ENTRY_PIXBUF, True) 


self.drop_area.drag_dest_set_target_list (targets) 
self.iconview.drag_source_set_target_list (targets) 


def add_text_targets(self, button=None) : 


self.drop_area.drag_dest_set_target_list (None) 
self.iconview.drag_source_set_target_list (None) 


self.drop_area.drag_dest_add_text_targets () 
self.iconview.drag_source_add_text_targets () 


class DragSourcelconView(Gtk.IconView) : 
def _init_ (self): 


Gtk.IconView. _init_ (self) 
self.set_text_column (COLUMN_TEXT) 
self.set_pixbuf_column (COLUMN_PIXBUF) 


model = Gtk.ListStore(str, GdkPixbuf.Pixbuf) 
self .set_model (model) 

self.add_item("Item 1", "image-missing") 
self.add_item("Item 2", "help-about") 
self.add_item("Item 3", "edit-copy") 


self.enable_model_drag_source (Gdk.ModifierType.BUTTON1_MASK, [], DRAG_ACTION) 
self.connect ("drag-data-get", self.on_drag_data_get) 


def on_drag_data_get (self, widget, drag_context, data, info, time): 


selected_path = self.get_selected_items () [0] 
selected_iter = self.get_model () .get_iter(selected_path) 


if info == TARGET_ENTRY_TEXT: 
text = self.get_model () .get_value (selected_iter, COLUMN_TEXT) 
data.set_text (text, -1) 

elif info TARGET_ENTRY_PIXBUF': 
pixbuf = self.get_model () .get_value (selected_iter, COLUMN_PIXBUF) 
data.set_pixbuf (pixbu£) 


def add _item(self, text, icon_name): 


pixbuf = Gtk.IconTheme.get_default () .load_icon (icon_name, 16, 0) 
self .get_model () .append ([text, pixbu£f]) 


class DropArea (Gtk.Label) : 
def __init__ (self): 


win 
win 
win 
Gtk 


Gtk.Label.__init__ (self) 
self.set_label ("Drop something on me!") 
self.drag_dest_set (Gtk.DestDefaults.ALL, [], DRAG_ACTION) 


self.connect ("drag-data-received", self.on_drag_data_received) 


def on_drag_data_received(self, widget, drag_context, x, y, data, info, time): 


if info TARGET_ENTRY_TEXT: 
text = data.get_text () 
print ("Received text: %s" % text) 


elif info 


TARGET_ENTRY_PIXBUF : 
pixbuf = data.get_pixbuf () 
width = pixbuf.get_width() 
height = pixbuf.get_height () 


print ("Received pixbuf with width %spx and height %spx" % (width, height)) 


DragDropWindow () 


.connect ("destroy", Gtk.main_quit) 
.show_all () 
.main () 
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22. Glade and Gtk.BuilderlAJ] 


The[ctk .Bui lderjclass offers you the opportunity to design user interfaces without writing a single line 
of code. This is achieved by defining the interface in an XML file and then loading that XML UI 


definition at runtime using the Builder class which creates the objects automatically. To avoid writing the 
XML manually use the application which lets you create the user interface in a WYSIWYG (what 
you see is what you get) manner 


This method has several advantages: 
e Less code needs to be written. 
e Ul changes can be seen more quickly, so Uls are able to improve. 
e Designers without programming skills can create and edit Uls. 


e The description of the user interface is independent from the programming language being used. 


There is still code required for handling interface changes triggered by the user, but[ctk. Builder] 
allows you to focus on implementing that functionality. 


22.1. Creating and loading the .glade file A7] 


First of all you have to download and install Glade. There are [several tutorials]about Glade, so this is not 
explained here in detail. Letás start by creating a window with a button in it and saving it to a file named 
example. glade. The resulting XML file should look like this. 


<?xml version="1.0" encoding="UTF-8"7?> 
<interface> 
<< interface-requires gtk+ 3.0 --> 


<object class="GtkWindow" id="windowl"> 
<property name="can_focus">False</property> 
<child> 
<object class="GtkButton" id="buttonl"> 
<property name="label" translatable="yes">button</property> 
<property name="use-action-appearance">False</property> 
<property name="visible">True</property> 
<property name="can-focus">True</property> 
<property name="receives-default">True</property> 
</object> 
</child> 
</object> 
</interface> 


To load this file in Python we need a object. 


builder = Gtk.Builder () 
builder.add_from_file("example.glade") 


The second line loads all objects defined in example. glade into the Builder object. 


It is also possible to load only some of the objects. The following line would add only the objects (and 
their child objects) given in the tuple. 


+ we don't really have two buttons here, this is just an example 
builder.add_objects_from_file("example.glade", ("buttonl1", "button2")) 


These two methods exist also for loading from a string rather than a file. Their corresponding names are 


Gtk.Builder.add_from_string()|land|[stk.Builder.add_objects_from_string() 


and they simply take a XML string instead of a file name. 


22.2. Accessing widgetdÁJ] 


Now that the window and the button are loaded we also want to show them. Therefore the 
Gtk.Window.show_all () method has to be called on the window. But how do we access the 
associated object? 


window = builder.get_objJect ("window1") 
window.show_all () 


Every widget can be retrieved from the builder by the[Gtk . Builder .get_object () [method and the 


widgetás id. It is really that simple. 


It is also possible to get a list of all objects with 


builder.get_objects() 


22.3. Connecting SignalsA Y] 


Glade also makes it possible to define signals which you can connect to handlers in your code without 
extracting every object from the builder and connecting to the signals manually. The first thing to do is to 
declare the signal names in Glade. For this example we will act when the window is closed and when the 
button was pressed, so we give the name áonDestroyá to the callback handling the ádestroyá signal of the 
window and aonButtonPressedá to the callback handling the ápressedá signal of the button. Now the XML 
file should look like this. 


<?xml version="1.0" encoding="UTF-8"7?> 
<interface> 
<I interface-requires gtk+ 3.0 --> 


<object class="GtkWindow" id="windowl"> 
<property name="can-focus">False</property> 
<signal name="destroy" handler="onDestroy" swapped="no"/> 
<child> 
<object class="GtkButton" id="buttonl"> 


<property name="label" translatable="yes">button</property> 
<property name="use-action-appearance">False</property> 
<property name="visible">True</property> 
<property name="can-focus">True</property> 
<property name="receives-default">True</property> 
<property name="use-action-appearance">False</property> 
<signal name="pressed" handler="onButtonPressed" swapped="no"/> 
</object> 
</child> 
</object> 
</interface> 


Now we have to define the handler functions in our code. The onDestroy should simply result in a call to 
Gtk.main_quit (). When the button is pressed we would like to print the string ¿Hello World!á, so we 
define the handler as follows 


def hello(button): 
print ("Hello World!") 


Next, we have to connect the signals and the handler functions. The easiest way to do this is to define a 
dict with a mapping from the names to the handlers and then pass it to the 
Gtk.Builder.connect_signals () [method. 


handlers = ( 
"onDestroy": Gtk.main_quit, 
"onButtonPressed": hello 


) 


builder.connect_signals (handlers) 


An alternative approach is to create a class which has methods that are called like the signals. In our 
example the last code snippet could be rewritten as: 


from gi.repository import Gtk 


class Handler: 
def onDestroy (self, *args): 
Gtk.main_quit () 


def onButtonPressed (self, button): 
print ("Hello World!") 
builder.connect_signals (Handler ()) 
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22.4. ExampleA Y] 


The final code of the example 


import gi 


gi.require_version("Gtk", "3.0") 
from gi.repository import Gtk 


class Handler: 
def onDestroy (self, *args): 
Gtk.main_quit () 


def onButtonPressed(self, button): 
print ("Hello World!") 


builder = Gtk.Builder () 
builder.add_from_file("builder_example.glade") 
builder.connect_signals (Handler ()) 


0 J0US WN ROwOoOJoadsyN Aa 


19 window = builder.get_object ("window1") 
20 window.show_all () 


22 Gtk.main () 


22.5. Gtk.TemplatdA Y] 
allows UI definition files to be used to extend a widget, PyGObject provides 
Gtk.Templatejas a way of accessing this from Python. 


The UI definition file used in the example needs a small change to include a <template> element: 


<?xml version="1.0" encoding="UTF-8"7?> 
<interface> 
<! interface-requires gtk+ 3.0 --> 


<template class="windowl" parent="GtkWindow"> 
<signal name="destroy" handler="onDestroy" swapped="no"/> 
<child> 
<object class="GtkButton" id="buttonl"> 
<property name="label" translatable="yes">button</property> 
<property name="use-action-appearance">False</property> 
<property name="visible">True</property> 
<property name="can-focus">True</property> 
<property name="receives-default">True</property> 
<property name="use-action-appearance">False</property> 
<signal name="pressed" handler="onButtonPressed" swapped="no"/> 
</object> 
</child> 
</template> 
</interface> 


Then it can be used to implement the example with a[stk . Wwindow/fsubclass: 


import gi 


gi.require_version("Gtk", "3.0") 
from gi.repository import Gtk 


(Gtk. Template (filename="templat 
class Windowl (Gtk.Window) : 
gtype_name = "windowl" 


xample.ui") 


(Gtk.Template.Callback () 
def onDestroy (self, *args): 
Gtk.main_quit () 


(Gtk.Template.Callback () 
def onButtonPressed(self, button): 
print ("Hello World!") 


0 J3J0 Us WN ROwOoOJoad4s gn Aa 


19 

20 window = Windowl () 
ZL window.show () 

22 

23 Gtk.main () 


More information can be found at the|PyGObject| website. 
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23. ObjectsA 
GObject is the fundamental type providing the common attributes and methods for all object types in 


GTK+, Pango and other libraries based on GObject. The [sobject . GObject]elass provides methods for 


object construction and destruction, property access methods, and signal support. 


This section will introduce some important aspects about the GObject implementation in Python. 


23.1. Inherit from GObject.GObjectAJ] 


A native GObject is accessible via[cObject . GObject] It is rarely instantiated directly, we generally 
use inherited class. A[Gtk . Widget]|is an inherited class of a[je6Object . GObject]| It may be interesting 
to make an inherited class to create a new widget, like a settings dialog. 

To inherit from|cObject .GObject] you must call GObject .GObject.__init__ () in your 
constructor (if the class inherits from|Gtk . Button] 1t must call Gtk.Button.__init__ () for 
instance), like in the example below: 

from gi.repository import GObject 

class MyObject (GObject.GObject) : 


def __init__ (self): 
GObject.GObject.__init__ (self) 


23.2. SignalsÁAY] 


Signals connect arbitrary application-specific events with any number of listeners. For example, in GTK+, 
every user event (keystroke or mouse move) is received from the X server and generates a GTK+ event 
under the form of a signal emission on a given object instance. 


Each signal is registered in the type system together with the type on which it can be emitted: users of the 
type are said to connect to the signal on a given type instance when they register a function to be invoked 
upon the signal emission. Users can also emit the signal by themselves or stop the emission of the signal 
from within one of the functions connected to the signal. 


23.2.1. Receive signalgAY] 

See|Main loop and Signals 

23.2.2. Create new signalgA] 

New signals can be created by adding them to[sobject .GObject._ _gsignals_ ] a dictionary: 


When a new signal is created, a method handler can also be defined, it will be called each time the signal 
1s emitted. Itis called do_signal_name. 


class MyObject (GObject.GObject) : 
__gsignals__ = ( 
“my_signal': (GObject.SIGNAL_RUN_FIRST, None, 
(int,)) 
) 


def do_my_signal (self, arg): 
print ("method handler for 'my_signal” called with argument", arg) 


GObject. SIGNAL RUN_FIRST|indicates that this signal will invoke the object method handler 
(do_my_signal () here) in the first emission stage. Alternatives are[cObject . SIGNAL _RUN_LAST 


(the method handler will be invoked in the third emission stage) and 


GObject.SIGNAL_RUN_CLEANUP|(invoke the method handler in the last emission stage). 


The second part, None, indicates the return type of the signal, usually None. 


(int, ) indicates the signal arguments, here, the signal will only take one argument, whose type is int. 
Types of arguments required by signal are declared as a sequence, here it is a one-element tuple. 


Signals can be emitted using[scObject .GObject .emit () 


my_ob3j.emit ("my_signal", 42) % emit the signal "my_signal", with the 
+ argument 42 


23.3. PropertiegÁJ] 


One of GObjectás nice features is its generic get/set mechanism for object properties. Each class inherited 


from|cObject . GObJect|can define new properties. Each property has a type which never changes (e.g. 
str, float, intá¡). For instance, they are used for|Gtk . Button|where there is a álabelá property which 
contains the text of the button. 


23.3.1. Use existing propertiesA |] 


The class[cObject . GObJect|provides several useful functions to manage existing properties, 
GObject .GObject .get_property () land[sobject .GObject .set_property() 


Some properties also have functions dedicated to them, called getter and setter. For the property álabelá of 
a button, there are two functions to get and set them, Gtk.Button.get_label () and 
Gtk.Button.set_label(). 


23.3.2. Create new propertiesA Y] 


A property is defined with a name and a type. Even if Python itself is dynamically typed, you canát change 
the type of a property once it is defined. A property can be created using GObject .Property. 


from gi.repository import GObject 

class MyObject (GObject.GObject) : 
foo = GObject.Property (type=str, default='bar') 
property_float = GObject.Property (type=float) 


def __init_ (self): 
GObject.GObject.__init__ (self) 


Properties can also be read-only, if you want some properties to be readable but not writable. To do so, 
you can add some flags to the property definition, to control read/write access. Flags are 


GObject .ParamFlags.READABLE|(only read access for external code), 
GObject .ParamFlags.WRITABLE|(only write access),|[cObject .ParamFlags.READWRITE 


(public): 


foo = GObject.Property (type=str, flags = GObject.ParamFlags.READABLE) + not writable 
bar GObject.Property (type=str, flags GObject.ParamFlags.WRITABLE) *+ not readable 


You can also define new read-only properties with a new method decorated with GObject .Property: 
from gi.repository import GObject 
class MyObject (GObject.GObject) : 


def __init__ (self): 
GObject.GObject.__init__ (self) 


fGObject .Property 
def readonly (self): 
return 'This is read-only.'” 


You can get this property using: 
my_object = MyObject () 


print (my_object.readonly) 
print (my_object.get_property ("readonly")) 


The API of GObject . Property is similar to the builtin property (). You can create property setter 
in a way similar to Python property: 


class AnotherO0bject (GObject .Object) : 
value = 0 


fGObject .Property 


def prop(self): 
"Read only property.” 
return 1 


fGObject .Property (type=int) 

def proplInt (self): 
"Read-write integer property.” 
return self.value 


f(propInt.setter 
def proplInt (self, value): 
self.value = value 


There is also a way to define minimum and maximum values for numbers, using a more verbose form: 


from gi.repository import GObject 
class MyObject (GObject.GObject) : 


__Ggproperties__=( 
"int-prop": (int, ++ type 

"integer prop", * nick 
"A property that contains an integer", + blurb 
1, + min 
5, + max 
2, * default 
GObject.ParamFlags.READWRITE + flags 


), 


def __init__ (self): 
GObject.GObject.__init__ (self) 
self.int_prop = 2 


def do_get_property (self, prop): 
if prop.name == 'int-prop': 
return self.int_prop 
else: 
raise AttributeError (“unknown property %s” $ prop.name) 


def do_set_property (self, prop, value): 
if prop.name == 'int-prop': 
self.int_prop = value 
else: 
raise AttributeError (“unknown property %s” $ prop.name) 


Properties must be defined in|scObject .GObject._ gproperties_ ladictionary, and handled in 


do_get_property and do_set_property. 


23.3.3. Watch propertiesAY] 


When a property is modified, a signal is emitted, whose name is ánotify::property-nameá: 


my_object = MyObject () 


def on_notify_foo(obj, gparamstring): 
print ("foo changed") 


my_object .connect ("notify::foo", on_notify_foo) 


my_object.set_property("foo", "bar") * on_notify_foo will be called 


Note that you have to use the canonical property name when connecting to the notify signals, as explained 


in[cObject .Object.signals.notify () | For instance, for a Python property foo_bar_baz you 


would connect to the signal notify: :foo-bar-baz using 
my_object = MyObject () 


def on_notify_foo_bar_baz(obj, gparamstring): 
print ("foo_bar_baz changed") 


my_object.connect ("notify::foo-bar-baz", on_notify_foo_bar_baz) 


23.4. APIAJ] 


class GObject .GObje ctAl 
get_prope rty(property_name]Al] 


Retrieves a property value. 


set_property(l(property_name, valueJA] 
Set property property_name to value. 
emit(signal_name, ... 


Emit signal signal_name. Signal arguments must follow, e.g. if your signal is of type (int,), 
1t must be emitted with: 


self.emit (signal_name, 42) 
freeze_noti£y(]Al 


This method freezes all the ánotify::á signals (which are emitted when any property is changed) 


until thelthaw_not if y () [method is called. 
It is recommended to use the with statement when calling[freeze_notify () | that way it is 


ensured that[thaw_not if y () lis called implicitly at the end of the block: 


with an_object.freeze_notify(): 
+ Do your work here 


thaw_noti £y (A 
Thaw all the ánotify::á signals which were frozen by|freeze_notify () 
It is recommended to not calllthaw_noti fy () Jexplicitly but uselfreeze_notify () 


together with the with statement. 
handler bl ock(handler_id]| Ag) 


Blocks a handler of an instance so it will not be called during any signal emissions unless 

is called for that handler_id. Thus áblockingá a signal handler means 
to temporarily deactivate 1t, a signal handler has to be unblocked exactly the same amount of 
times it has been blocked before to become active again. 


It is recommended to uselhandler_block () [in conjunction with the with statement which 


will calllhandler_unblock () Jimplicitly at the end of the block: 


with an_object.handler_block (handler_id): 
+ Do your work here 


handler_unblock(handler_id] Ag] 
Undoes the effect of|hhandler_block ()| A blocked handler is skipped during signal 


emissions and will not be invoked until it has been unblocked exactly the amount of times it has 
been blocked before. 


It is recommended to not calllhand1er_unblock () Jexplicitly but uselhand1er_block () 


together with the with statement. 


__gsignals 
A dictionary where inherited class can define new signals. 


Each element in the dictionary is a new signal. The key is the signal name. The value is a tuple, 
with the form: 


(GObject.SIGNAL_RUN_FIRST, None, (int,)) 


GObject.SIGNAL_RUN_FIRST[|can be replaced with[sObject . SIGNAL_RUN_LAST|or 


Object. SIGNAL_RUN_CLEANUP| None is the return type of the signal. (int, ) is the 
tuple of the parameters of the signal. 


__gproperties 


The|__gproperties__Idictionary is a class property where you define the properties of your 


object. This is not the recommended way to define new properties, the method written above is 
much less verbose. The benefits of this method is that a property can be defined with more 
settings, like the minimum or the maximum for numbers. 


The key is the name of the property 


The value is a tuple which describe the property. The number of elements of this tuple depends 
on its first element but the tuple will always contain at least the following items: 


The first element is the propertyás type (e.g. int, floatá;). 


The second element is the propertyás nick name, which is a string with a short description 
of the property. This is generally used by programs with strong introspection capabilities, 
like the graphical user interface builder 


The third one is the propertyás description or blurb, which is another string with a longer 
description of the property. Also used by and similar programs. 


The last one (which is not necessarily the forth one as we will see later) is the propertyás 
flags: GObject . PARAM_READABLE, GObject .PARAM_WRITABLE, 
GObject.PARAM_READWRITE. 


The absolute length of the tuple depends on the property type (the first element of the tuple). 
Thus we have the following situations: 


If the type is bool or str, the forth element is the default value of the property. 


If the type is int or float, the forth element is the minimum accepted value, the fifth 
element is the maximum accepted value and the sixth element is the default value. 


If the type is not one of these, there is no extra element. 

GObject .SIGNAL_RUN_FIRSTAI] 

Invoke the object method handler in the first emission stage. 
GObject .SIGNAL_RUN_LASTAJ] 

Invoke the object method handler in the third emission stage. 
GObject .SIGNAL_RUN_CLEANURAJ] 

Invoke the object method handler in the last emission stage. 
GObject .ParamFlags . READABLHAY] 

The property is readable. 
GObject .ParamFlags.WRITABLHAJ] 


The property is writable. 


GObject .ParamFlags. READWRITHAJ] 


The property is readable and writable. 
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24. ApplicatiorlAJ] 


Gtk.Applicationjencompasses many repetitive tasks that a modern application needs such as 


handling multiple instances, D-Bus activation, opening files, command line parsing, startup/shutdown, 
menu management, window management, and more. 


24.1. ActiongAJ] 


is a way to expose any single task your application or widget does by a name. These 
actions can be disabled/enabled at runtime and they can either be activated or have a state changed (1f they 
contain state). 


The reason to use actions is to separate out the logic from the Ul. For example this allows using a menubar 
on OSX and a gear menu on GNOME both simply referencing the name of an action. The main 


implementation of this you will be using is[¡Gio. SimpleAct i¡on|which will be demonstrated later. 
Many classes such as[Gio . MenulItemjand|Gtk. Mode 1But ton|support properties to set an action 


name. 


These actions can be grouped together into a[6io.ActionGroupland when these groups are added to a 


widget with[Gtk . Widget. insert_action_group ()|they will gain a prefix. Such as áwiná when 
added to a[Gtk . ApplicationWindow| You will use the full action name when referencing it such as 


áapp.aboutá but when you create the action 1t will just be áaboutá until added to the application. 


You can also very easily make keybindings for actions by setting the accel property in the [sio . Menulfile 


or by using[Gtk.Application.set_accels_for_action() 


24.2. MenusÁAJ] 


Y our menus should be defined in XML using[sio.MenuJand would reference the previously mentioned 
actions you defined. allows you to set a menu either via 

or[6tk Application .set_menubar ()] If you make 
use of this can automatically use the correct menu based on platform, otherwise you can 
set them manually. A detailed example is shown below. 


24.3. Command LindAY] 
When creating your application it takes a flag property of Using this you 


can let it handle everything itself or have more custom behavior. 


You can use HANDLES_COMMAND_LINE to allow custom behavior in 


Gio.Application.do_command_line ()| In combination with 


Gio.Application.add_main_option ()|to add custom options. 


Using HANDLES_OPEN will do the work of simply taking file arguments for you and let you handle it in 
Gio.Application.do_open () 


If your application is already open these will all be sent to the existing instance unless you use 
NON_UNIQUE to allow multiple instances. 


24.4. ExampleAJ] 


String 1 


String 2 


String 3 


Maximize 


import sys 
import gi 


gi.require_version("Gtk", 13.0%) 
from gi.repository import GLib, Gio, Gtk 


4 This would typically be its cun file 
MENU_XML = "o" 


<?xml version="1.0" encoding="LTF-8"2> 
<interface> 
<menu ¿d="app-menu"> 
<section> 
<attribute name="label" translatable="yes">Change label</attribute> 
<item> 


<attribute nam 
<attribute nam 
<attribute nam 
</item> 
<item> 
<attribute name="action">win.change_label</attribute> 
<attribute name="target">String 2</attribute> 
<attribute name="label" translatable="yes">String 2</attribute> 
</item> 
<item> 
<attribute 
<attribute 
<attribute 
</item> 
</section> 
<section> 
<item> 
<attribute nam 
<attribute nam 
</item> 
</section> 
<section> 
<item> 
<attribute nam 
<attribute nam 
</item> 
<item> 
<attribute name="action">app.quit</attribute> 
<attribute name="label" translatable="yes">_Quit</attribute> 
<attribute name="accel">61t;Primary£gt;g</attribute> 
</item> 
</section> 
</menu> 


</interface> 


'action">win.change_label</attribute> 
targer">String 1</attribute> 
label" translatable="yes">String 1</attribute> 


'action">win.change_label</attribute> 
"targer">String 3</attribute> 
label" translatable="yes">String 3</attribute> 


'action">win.maximize</attribute> 
"label" translatable="yes">Maximize</attribute> 


action">app. about</attribute> 
label" translatable="yes">_About</attribute> 


class AppiWindow(Gtk.Applicationindow 
def _init__ (self, targs, *'kwargs): 
super()._init__(*args, **kwargs) 


* This ill be in the windows group and have the "win" prefix 
max_action = Gio.Simpleñction.new_stateful ( 

"maximize", None, GLib.Variant .new_boolean (False) 
) 
max_action.connect ("change-state", self.on_maximize_toggle) 
self.add_action (max_action) 


H Keep it in sync with the actual state 
self .connect ( 
"notify: :is-maximized", 
lambda obj, pspec: max_action.set_state( 
GLib.Variant .new_boolean (obj.props.is_maximized) 


da, 
) 


1b1_variant = GLib.Variant.new_string("String 1") 
1bl_action = Gio.SimpleAction.new_stateful ( 

"change_label", lbl_variant.get_type(), 1bl_variant 
) 
1b1_action.connect ("change-state", self.on_change_label_state) 
self.add_action(1b1_action) 


self.label = Gtk.Label (label=1b1_variant.get_string(), margi 
self.add(self.labe1) 
self.label.show() 


def on_change_label_state(self, action, value): 
action.set_state (value) 
self.label.set_text (value.get_string()) 


def on_maximize_toggle(self, action, value): 
action.set_state (value) 
if value.get_boolean (): 
self.maximize () 
else: 
self.unmaximize () 


class Application (Gtk.Application) : 
def _init__ (self, vargs, *'kwargs): 
super()._imit_( 
*args, 
application_id="org.example.myapp", 
£lags=Gio.ApplicationFlags .HANDLES_COMMAND_LINE, 
**kuargs 


) 


self.window = None 


self.add_main_option( 
"test", 
ord("e”), 
GLib.OptionFlags .NONE, 
GLib. Opt ionArg.NONE, 
"Command line test", 
None, 


) 


def do startup (self, 
Gtk.Application.do_startup(sel£) 


action = Gio.Simpleaction.new("about", None) 
action.connect ("activate", self.on_about) 
self.add_action (action) 


action = Gio.Simpleaction.new("quit", None) 
action.connect ("activate", self.on_quit) 
self.add_action (action) 


builder = Gtk.Builder.new_from_string (MENU_XML, -1) 
self.set_app_menu (builder.get_object ("app-menu")) 


def do activate(sel£): 
* He only allow a single window and raise any existing ones 
Í£ not self.window: 
4 Windows are associated with the application 
4 when the last one is closed the application shuts down 
self.window = AppiWindow(application=self, title="Main Window") 


self .window.present () 


def do_command_line(self, command_line) : 
options = command _line.get_options_dict () 
k convert GVariantDict -> GVariant -> dict 
options = options.end() .unpack () 


if "test" in options: 
4 This is printed on the main instance 
print ("Test argument recieved: %s" $ options["test"]) 


self.activate() 
return 0 


def on_about (self, action, param): 
about_dialog = Gtk.AboutDialog (transient_£o; 
about_dialog.present () 


.elf window, modal=True) 


def on quit (self, action, param): 
sel£.quit () 


1£ name == "main ": 
app = Application() 


app.run (sys.argv) 


24.5. See AlsoAJ] 
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MenusAf]| 


Note 


Gtk .UlManager||[Gtk.Action|and|Gtk. Act ionGroup|have been deprecated since GTK+ version 
3.10 and should not be used in newly-written code. Use the framework instead. 


GTK+ comes with two different types of menus, |Stk .MenuBarland|[Gtk.Toolbar||6tk.MenuBar 
re[Gtk . MenuTt en] 


1s a standard menu bar which contains one or more|Gtk . MenulItemjinstances or one of its subclasses. 


Gtk.Toolbar|widgets are used for quick accessibility to commonly used functions of an application. 
Examples include creating a new document, printing a page or undoing an operation. It contains one or 


more instances of|ctk . Tool Itenmjor one of its subclasses. 


ActionsÁJ] 


Although, there are specific APIs to create menus and toolbars, you should use and 
create instances. Actions are organised into groups. a 
a o All actions that would make sense to use in a particular 
context should be in a single group. Multiple action groups may be used for a particular user interface. In 
fact, it is expected that most non-trivial applications will make use of multiple groups. For example, in an 
application that can edit multiple documents, one group holding global actions (e.g. quit, about, new), and 
one group per document holding actions that act on that document (eg. save, cut/copy/paste, etc). Each 
windowás menus would be constructed from a combination of two action groups. 


Different classes representing different types of actions exist: 


An action which can be triggered by a menu or toolbar item 
An action which can be toggled between two states 
An action of which only one in a group can be active 
An action of which represents a list of recently used files 


Actions represent operations that the user can perform, along with some information how it should be 
presented in the interface, including its name (not for display), its label (for display), an accelerator, 
whether a label indicates a tooltip as well as the callback that is called when the action gets activated. 


You can create actions by either calling one of the constructors directly and adding them to a 


Gtk.ActionGrouplby calling[stk. ActionGroup.add_action () Jor 
Gtk.ActionGroup.add_action_with_accel ()| or by calling one of the convenience functions: 


O [Gtk.ActionGroup.add_actions ()| 


O [Gtk.ActionGroup.add_toggle_actions() 
O [Gtk.ActionGroup.add_radio_actions() 


Note that you must specify actions for sub menus as well as menu items. 


UI ManagerA]] 
[Stk .UIManager]|provides an easy way of creating menus and toolbars using an|XML-like description 


First of all, you should add the|[stk . ActionGrouplto the Ul Manager with 
Gtk.UlManager.insert_action_group ()| At this point is also a good idea to tell the parent 


window to respond to the specified keyboard shortcuts, by using 


Gtk.UlManager .get_accel_group () land[Gtk.Window.add_accel_group() 


Then, you can define the actual visible layout of the menus and toolbars, and add the UI layout. This áui 
stringá uses an XML format, in which you should mention the names of the actions that you have already 
created. Remember that these names are just the identifiers that we used when creating the actions. They 
are not the text that the user will see in the menus and toolbars. We provided those human-readable names 
when we created the actions. 


Finally, you retrieve the root widget with|[6tk. UlManager .get_widget () [and add the widget to a 
container such as[Gtk . Box 


ExampldAY] 


Menu Example 


File Edit  Choices 


5 Es 


Right-click to see the popup menu 


import gi 


gi.require_version("Gtk", 3,0%) 
from gi. repository import Gtk, Gák 


<ul> 
<menubar name="MenuBar'> 


> <menu action='Fi1etleny”> 
10 <nenu action="F11eNew> 

n <menuitem action="FileNewstandard" /> 

2 <menuitem action="FileNenFoo! /> 

1 <menuitem action="FileNenGoo" /> 

14 </mem> 

15 <separator /> 

16 <nenuitem action="FileQuit” /> 

n </memu> 

18 <menu actions! Editieny!> 

19 <nenuitem action="Editcopy” /> 

20 <nenuitem action="EditPaste” /> 

21 <menuitem action="EditSomerning” /> 

2 </menu> 

2 <menu action='Choicestens!> 

24 <nenuitem action="Choiceone! /> 

25 <nenuitem action="Choicetwo! /> 

26 <separator /> 

21 <nenuitem action="Choicethree” /> 

28 </menu> 

29 </memubar> 

30 <toulbar name="ToolBar'> 

EN <toolitem action="Plleleustandard” /> 

2 <toolitem action="Pileguie” /> 

33 </toolbar> 

34 <popup name="PopupMenu”> 

ES <menuitem action="EditCopy! /> 

36 <menuitem action="EditPaste! /> 

ES] <menuitem action="EditSomething” /> 

38 </popup> 

39 <ul> 

a 

4 

42 

43 class MenuExamplelvindow(Gtk .Hindow) + 

44 def _init_ (self: 

45 Super()._imit_ (title="enu Example") 

46 

41 self.set_default_size(200, 200) 

40 

49 action_growp = Grk.ActionGroup (nane="my_actions") 
50 

51 self.add_file_menu_actions (action_group) 

52 selfadd_edit_menu_actions (action_group) 

53 self.add_choices_menu_actions (action_group) 

54 

55 vimanager = self.create_ul_manager () 

56 uimanager. insert_action_group (action_group) 

E] 

58 menubar - uinanager.get_widget (*/Menubar") 

59 

50 box - Gtk.Box(orientation=Gtk Orientation. VERTICAL) 
6 box.pack_start (menubar, False, False, 0) 

62 

6 toolbar - uimanager.get_widget (*/ToolBar") 

61 box.pack_start (toolbar, False, False, 0) 

6s 

66 eventbox - Gtk.EventBox() 

61 “eventbox.connect ("button-press-event", self.on button press_event) 
68 box.pack_start (eventbox, True, True, 0) 

59 

70 label - Gtk.Label (label="Right-click to see the popup menu." 
na eventbox.add (label) 

7 

73 self.popup = uimanager.get_widget ("/Popuptenu") 

74 

75 self.add(box) 

76 

n def add_file_menu_actions(self, action_group) 

78 acrion_filemenu = Gtk.Actión (name="FileMenu", label="PL1e") 
79 acrion_group.add_action(action_ilemenu) 

80 

el action_fileneumenu - Gtk.Action(name="FileNew", stock_1d=GEk. STOCK_NEM) 
82 action_group.add_action (aceion_£i lenenmenuj) 

83 

24 action_new = Gtk.Action( 

as name="Pi1enewStandard", 

86 Label="_New", 

E] tooltip="create a new file", 

se Stock_ld-Stk.STOCK_NEM, 

E ) 

90 action_nem.connect (Tactivate", self.on_menu_file_new generic) 
31 action_group.add_action_with_accel (action_new, None) 
92 

ES action_group.add_actions ( 

34 ( 

95 ( 

96 "piLeNewE0o", 

E] None, 

90 "iu Foo", 

99 None, 

100 "create neu foo", 

101 sel£.on_menu_£i1e_nem_generic, 

102 » 

103 ( 

104 "BsLeNeRG00", 

105 None, 

106 "_New 600", 

107 None, 

108 "create neu goo", 

109 sel£.on_menu_£i18_new_generic, 

119 » 

1 1 

112 , 

113 

114 action_filequit - Gtk.Action(name="FileQuit", stock_id=GtX.STOCK_QUIT) 
15 action_filequit .connect ("activate", self.on_nenu file quit) 
116 acrion_group.add_action(aceion_filequit) 

11 

118 def add_edit_menu_actions (self, action_group) + 

19 action_group.add_actions ( 

120 ( 

121 ("editmenu", None, "Edit", 

122 ("EditCOpy", Gtk.STOCK_COPY, None, None, None, self.on_menu others), 
123 ("editpaste", Gtk.STOCK PASTE, None, None, None, Self.on_menu_others), 
124 ( 

125 "sditsomething", 

126 None, 

121 "something". 

128 "<control><alt>s", 

129 None, 

130 self.on_menu_others, 

m Y 

132 1 

13 ) 

14 

15 def add_choices_menu_actions (self, action_group) 

136 action_group.add_action(Gtk.ACtion (name="Cholcestenu", 1abel="Choices")) 
137 

138 acrion_group.add_radio_actions ( 

19 ( 

140 ("choiceone", None, "One", None, None, 1), 
141 ("ChoiceTwo", None, "Two", None, None, 2), 
142 » 

143 L 

144 se1£.on_menu_choices_changed, 

1as , 

146 

147 three - Gtk.ToggleAction(name="ChoiceThres", 1abel="Three") 
148 three.connect (“toggled", self.on_menu_cholces_togglea) 
149 action_group.add_action (three) 

150 

151 def create_ui_manager (self): 

152 uimanager = Grk.UIManager () 

153 

154 Y throws exception £f somerhing went wrong 

155 vimanager.add_ul_£rom_string (UI_INFO) 

156 

157 Y add the accelerator group to the toplevel window 
158 accelgroup - uimanager.get_accel_group () 

159 self.add_accel_group(accelgroup) 

160 retuín vinanager 

161 

162 def on_menu_file_neu_generto(sel£, widget): 

163 print("a File|new menu iten was selected.") 

164 

165 def on_menu file quit (sel£, widget): 

166 Gtk.main_quie () 

161 

168 def on_menu_others (self, widget): 

169 print("Menu item " + widget.get_name() + " was selected") 
170 

m def on_menu_choices_changed (self, widget, current): 
172 print (current.get_name() + * was selected.") 

173 

174 def on_menu_choices_toggled (self, widget): 

175 Af widger.get_acelve(): 

176 print (utdget.get_name () + " activated") 

m else: 

178 print (uidget.get_name () + " deactivated") 

179 

180 def onburton_press_event (self, widget, event): 

181 Y check 1f right mouse button was preseed 

182 1£ event.type == Gak.EventIype.BUTTON_PRESS and event.button == 3 
183 self. pOpup.popupÍNlone, None, None, None, event.button, event.time) 
184 return True A event has been handled 

185 

186 


187 — window - MenuExampleltindow() 
188 — windou.connect ("destroy", Gtk.main_quit) 
189 — window.show_a11() 

190 — Gtk.main() 
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TabldÁJ] 
Note 


has been deprecated since GTK+ version 3.4 and should not be used in newly-written code. 
Use the[Grid[class instead. 


Tables allows us to place widgets in a grid similar to 


The gridás dimensions need to be specified in the|[etk . Tablelconstructor. To place a widget into a box, 


use[Gtk.Table.attach () 
Gtk.Table.set_row_spacing ()land[Gtk. Table.set_col_spacing() |set the spacing 


between the rows at the specified row or column. Note that for columns, the space goes to the right of the 
column, and for rows, the space goes below the row. 


You can also set a consistent spacing for all rows and/or columns with 


Gtk.Table.set_row_spacings ()/Jand|[Gtk.Table.set_col_spacings ()| Note that with 


these calls, the last row and last column do not get any spacing. 


Deprecated since version 3.4: It is recommended that you use the|Gtk . Gridjfor new code. 


ExampleAY] 


Table Example 


Button 1 Button 2 


Button 4 
Button 3 
Button 5 Button 6 


import gi 


gi.require_version("Gtk", "3.0") 
from gi.repository import Gtk 


class TableWindow(Gtk.Window) : 
def __init__ (self): 
super ().__init__(title="Table Example") 


table = Gtk.Table(n_rows=3, n_columns=3, homogeneous=True) 
self.add (table) 


buttonl = Gtk.Button(label="Button 1") 
button2 = Gtk.Button (label="Button 2") 
button3 = Gtk.Button(label="Button 3") 
button4 = Gtk.Button (label="Button 4") 
button5 = Gtk.Button(label="Button 5") 

6") 


0 J0 Us WNROwOoO Jocs yn Aa 


19 button6 = Gtk.Button (label="Button 6" 
20 

21 table.attach(button1, 0, 1, O, 1) 
22 table.attach(button2, 1, 3, 0, 1) 
23 table.attach(button3, 0, 1, 1, 3) 
24 table.attach (button4, 1, 3, 1, 2) 
25 table.attach(button5, 1, 2, 2, 3) 
26 table.attach(button6, 2, 3, 2, 3) 
27 

28 

29 win = TableWindow () 

30 win.connect ("destroy", Gtk.main_quit) 

31 win.show_all() 

BEA Gtk.main () 
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